Merge branch 'main' into feature/prefixed-archives

.github/workflows/_lint-docs.yml

@@ -0,0 +1,14 @@
+name: Lint documentation
+
+on:
+  push:
+    paths:
+      - '**.md'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  wp-scripts-lint:
+    uses: inpsyde/reusable-workflows/.github/workflows/wp-scripts-lint.yml@main
+    with:
+      LINT_TOOLS: '["md-docs"]'

.github/workflows/automatic-release.yml

@@ -1,9 +1,30 @@
 name: Automatic Release
 on:
   workflow_call:
+    inputs:
+      NPM_REGISTRY_DOMAIN:
+        description: Domain of the private npm registry.
+        default: https://npm.pkg.github.com/
+        required: false
+        type: string
     secrets:
+      NPM_REGISTRY_TOKEN:
+        description: Authentication for the private npm registry.
+        required: false
+      GITHUB_USER_EMAIL:
+        description: Email address for the GitHub user configuration.
+        required: false
+      GITHUB_USER_NAME:
+        description: Username for the GitHub user configuration.
+        required: false
+      GITHUB_USER_SSH_KEY:
+        description: Private SSH key associated with the GitHub user for the token passed as `GITHUB_USER_TOKEN`.
+        required: false
+      GITHUB_USER_SSH_PUBLIC_KEY:
+        description: Public SSH key associated with the GitHub user for the token passed as `GITHUB_USER_TOKEN`.
+        required: false
       GITHUB_USER_TOKEN:
-        description: Authentication token with write permission needed by the release bot (falls back to GITHUB_TOKEN).
+        description: Authentication token with write permission needed by the release bot (falls back to `GITHUB_TOKEN`).
         required: false
 
 jobs:
@@ -13,6 +34,9 @@ jobs:
     runs-on: ubuntu-latest
     env:
       HAS_CONFIG: false
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_REGISTRY_TOKEN }}
+      GITHUB_USER_SSH_KEY: ${{ secrets.GITHUB_USER_SSH_KEY }}
+      GITHUB_USER_SSH_PUBLIC_KEY: ${{ secrets.GITHUB_USER_SSH_PUBLIC_KEY }}
     steps:
       - name: Fetch semantic-release Node version
         uses: actions/checkout@v4
@@ -23,10 +47,11 @@ jobs:
           sparse-checkout-cone-mode: false
           path: semantic-release-repo
 
-      - name: Setup Node.js
+      - name: Set up node
         uses: actions/setup-node@v4
         with:
           node-version-file: semantic-release-repo/package.json
+          registry-url: ${{ inputs.NPM_REGISTRY_DOMAIN }}
 
       - name: Install dependencies
         run: |
@@ -40,7 +65,25 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           persist-credentials: false
+          ssh-key: ${{ env.GITHUB_USER_SSH_KEY }}
+
+      - name: Set up SSH
+        if: ${{ env.GITHUB_USER_SSH_KEY != '' }}
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ env.GITHUB_USER_SSH_KEY }}
+
+      - name: Set up signing commits
+        if: ${{ env.GITHUB_USER_SSH_PUBLIC_KEY != '' }}
+        run: |
+          : # Create empty SSH private key file so Git does not complain.
+          touch "${{ runner.temp }}/signingkey"
+          echo "${{ env.GITHUB_USER_SSH_PUBLIC_KEY }}" > "${{ runner.temp }}/signingkey.pub"
+          git config --global commit.gpgsign true
+          git config --global gpg.format ssh
+          git config --global user.signingkey "${{ runner.temp }}/signingkey.pub"
 
       - name: Check presence of release.config.js
         run: |
@@ -67,7 +110,23 @@ jobs:
         run: |
           rm -rf workflow-repo
 
+      - name: Set up release environment variables
+        env:
+          GITHUB_USER_EMAIL: ${{ secrets.GITHUB_USER_EMAIL }}
+          GITHUB_USER_NAME: ${{ secrets.GITHUB_USER_NAME }}
+        run: |
+          ${{ env.GITHUB_USER_EMAIL != '' }} && echo "GIT_AUTHOR_EMAIL=${{ env.GITHUB_USER_EMAIL }}" >> $GITHUB_ENV || true
+          ${{ env.GITHUB_USER_NAME != '' }} && echo "GIT_AUTHOR_NAME=${{ env.GITHUB_USER_NAME }}" >> $GITHUB_ENV || true
+          ${{ env.GITHUB_USER_EMAIL != '' }} && echo "GIT_COMMITTER_EMAIL=${{ env.GITHUB_USER_EMAIL }}" >> $GITHUB_ENV || true
+          ${{ env.GITHUB_USER_NAME != '' }} && echo "GIT_COMMITTER_NAME=${{ env.GITHUB_USER_NAME }}" >> $GITHUB_ENV || true
+
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_USER_TOKEN != '' && secrets.GITHUB_USER_TOKEN || secrets.GITHUB_TOKEN }}
         run: npx semantic-release
+
+      - name: Delete signing key files
+        if: ${{ always() && env.GITHUB_USER_SSH_PUBLIC_KEY != '' }}
+        run: |
+          rm -f "${{ runner.temp }}/signingkey"
+          rm -f "${{ runner.temp }}/signingkey.pub"

.github/workflows/build-and-push-assets.yml

@@ -53,11 +53,6 @@ on:
         default: ''
         required: false
         type: string
-      BUILT_BRANCH_SUFFIX:
-        description: Suffix to calculate the target branch for pushing assets on the `branch` event (deprecated).
-        type: string
-        default: ''
-        required: false
       BUILT_BRANCH_NAME:
         description: Sets the target branch for pushing assets on the `branch` event.
         type: string
@@ -91,6 +86,9 @@ on:
       GITHUB_USER_SSH_KEY:
         description: Private SSH key associated with the GitHub user passed as `GITHUB_USER_NAME`.
         required: false
+      GITHUB_USER_SSH_PUBLIC_KEY:
+        description: Public SSH key associated with the GitHub user passed as `GITHUB_USER_NAME`.
+        required: false
       ENV_VARS:
         description: Additional environment variables as a JSON formatted object.
         required: false
@@ -142,17 +140,13 @@ jobs:
       GITHUB_USER_EMAIL: ${{ secrets.GITHUB_USER_EMAIL }}
       GITHUB_USER_NAME: ${{ secrets.GITHUB_USER_NAME }}
       GITHUB_USER_SSH_KEY: ${{ secrets.GITHUB_USER_SSH_KEY }}
+      GITHUB_USER_SSH_PUBLIC_KEY: ${{ secrets.GITHUB_USER_SSH_PUBLIC_KEY }}
       COMPILE_SCRIPT: ''
       TAG_NAME: ''                                     # we'll override if the push is for tag
       TAG_BRANCH_NAME: ''                              # we'll override if the push is for tag
       LOCK_FILE: ''                                    # we'll override after checking files
       NO_CHANGES: ''                                   # we'll override if no changes to commit
     steps:
-      - name: Deprecation warning
-        if: ${{ inputs.BUILT_BRANCH_SUFFIX != '' }}
-        run: |
-          echo '::warning::The BUILT_BRANCH_SUFFIX input is deprecated and will be removed soon. Please update your workflow to use BUILT_BRANCH_NAME with ${{ github.ref_name }}-built.'
-
       - name: Checkout
         uses: actions/checkout@v4
         with:
@@ -172,6 +166,16 @@ jobs:
           git config --global advice.addIgnoredFile false
           git config --global push.autoSetupRemote true
 
+      - name: Set up signing commits
+        if: ${{ env.GITHUB_USER_SSH_PUBLIC_KEY != '' }}
+        run: |
+          : # Create empty SSH private key file so Git does not complain.
+          touch "${{ runner.temp }}/signingkey"
+          echo "${{ env.GITHUB_USER_SSH_PUBLIC_KEY }}" > "${{ runner.temp }}/signingkey.pub"
+          git config --global commit.gpgsign true
+          git config --global gpg.format ssh
+          git config --global user.signingkey "${{ runner.temp }}/signingkey.pub"
+
       - name: Set up custom environment variables
         env:
           ENV_VARS: ${{ secrets.ENV_VARS }}
@@ -198,7 +202,7 @@ jobs:
       - name: Set branch environment variables
         if: ${{ github.ref_type == 'branch' }}
         run: |
-          echo "BUILT_BRANCH_NAME=${{ inputs.BUILT_BRANCH_NAME && inputs.BUILT_BRANCH_NAME || format('{0}{1}', github.ref_name, inputs.BUILT_BRANCH_SUFFIX) }}" >> $GITHUB_ENV
+          echo "BUILT_BRANCH_NAME=${{ inputs.BUILT_BRANCH_NAME && inputs.BUILT_BRANCH_NAME || github.ref_name }}" >> $GITHUB_ENV
 
       - name: Set tag environment variables
         if: ${{ github.ref_type == 'tag' }}
@@ -209,18 +213,18 @@ jobs:
       - name: Checkout and merge the built branch
         if: ${{ github.ref_type == 'branch' }}
         run: |
-          git checkout ${{ env.BUILT_BRANCH_NAME }} || git checkout -b ${{ env.BUILT_BRANCH_NAME }}
+          git show-ref -q refs/remotes/origin/${{ env.BUILT_BRANCH_NAME }} && git checkout ${{ env.BUILT_BRANCH_NAME }} || git checkout -b ${{ env.BUILT_BRANCH_NAME }}
           git merge ${{ github.ref_name }}
 
       - name: Git pull on re-run
         if: ${{ (github.run_attempt > 1) && (github.ref_type != 'tag') }}
-        run: git pull
+        run: git show-ref -q refs/remotes/origin/$(git branch --show-current) && git pull || true
 
       - name: Checkout and merge the release branch
         if: ${{ github.ref_type == 'tag' && env.RELEASE_BRANCH_ENABLED == 'yes' }}
         run: |
           git checkout ${{ github.event.repository.default_branch }}
-          git checkout ${{ inputs.RELEASE_BRANCH_NAME }} || git checkout -b ${{ inputs.RELEASE_BRANCH_NAME }}
+          git show-ref -q refs/remotes/origin/${{ inputs.RELEASE_BRANCH_NAME }} && git checkout ${{ inputs.RELEASE_BRANCH_NAME }} || git checkout -b ${{ inputs.RELEASE_BRANCH_NAME }}
           git merge ${{ github.event.repository.default_branch }}
 
       - name: Checkout temporary tag branch
@@ -276,7 +280,7 @@ jobs:
           git commit -m "[BOT] Add compiled assets for #${{ github.ref }}" --no-verify || ((echo "NO_CHANGES=yes" >> $GITHUB_ENV) && (echo "No changes to commit"))
 
       - name: Git push for branch
-        if: ${{ github.ref_type == 'branch' && (env.NO_CHANGES != 'yes' || inputs.BUILT_BRANCH_SUFFIX != '') }}
+        if: ${{ github.ref_type == 'branch' && (env.NO_CHANGES != 'yes' || inputs.BUILT_BRANCH_NAME != '') }}
         run: git push
 
       - name: Git push for tag
@@ -297,3 +301,9 @@ jobs:
           git checkout --detach
           git branch -d ${{ env.TAG_BRANCH_NAME }}
           git push origin --delete ${{ env.TAG_BRANCH_NAME }}
+
+      - name: Delete signing key files
+        if: ${{ always() && env.GITHUB_USER_SSH_PUBLIC_KEY != '' }}
+        run: |
+          rm -f "${{ runner.temp }}/signingkey"
+          rm -f "${{ runner.temp }}/signingkey.pub"

.gitignore

@@ -1,2 +1,5 @@
 ## PhpStorm
 .idea/
+
+## npm
+/node_modules/

README.md

@@ -45,3 +45,7 @@ groups here:
 * [Create plugin archive](./docs/archive-creation.md)
 * [Automatic release](./docs/automatic-release.md)
 * [DDEV Playwright](./docs/ddev-playwright.md)
+
+**Note:**
+
+Workflow files prefixed with `_` are specific to the repository and cannot be reused.

docs/archive-creation.md

@@ -14,7 +14,7 @@ To achieve that, the reusable workflow:
 8. Runs `wp dist-archive` to create the final archive (with builtin support for a `.distignore` file)
 9. Uploads it as an artifact for download or further processing
 
-## Simple usage example:
+## Simple usage example
 
 ```yml
 name: Create release package

docs/assets-compilation.md

@@ -2,7 +2,7 @@
 
 This workflow utilizes
 the [Composer Asset Compiler](https://github.com/inpsyde/composer-asset-compiler) to compile assets.
-For details, refer to https://github.com/inpsyde/composer-asset-compiler#pre-compilation.
+For details, refer to [Pre-compilation](https://github.com/inpsyde/composer-asset-compiler#pre-compilation).
 
 **Simplest possible example:**
 
@@ -16,9 +16,9 @@ jobs:
     uses: inpsyde/reusable-workflows/.github/workflows/build-assets-compilation.yml@main
 ```
 
-### Configuration parameters
+## Configuration parameters
 
-#### Inputs
+### Inputs
 
 | Name                  | Default                       | Description                                                                       |
 |-----------------------|-------------------------------|-----------------------------------------------------------------------------------|
@@ -30,7 +30,7 @@ jobs:
 | `COMPOSER_ARGS`       | `'--prefer-dist'`             | Set of arguments passed to Composer                                               |
 | `COMPILE_ASSETS_ARGS` | `'-v --env=root'`             | Set of arguments passed to Composer Asset Compiler                                |
 
-#### Secrets
+### Secrets
 
 | Name                  | Description                                                                              |
 |-----------------------|------------------------------------------------------------------------------------------|

docs/automatic-release.md

@@ -42,11 +42,22 @@ jobs:
 
 ## Configuration parameters
 
+### Inputs
+
+| Name                  | Required | Default                         | Description                        |
+|-----------------------|----------|---------------------------------|------------------------------------|
+| `NPM_REGISTRY_DOMAIN` | false    | `'https://npm.pkg.github.com/'` | Domain of the private npm registry |
+
 ### Secrets
 
-| Name                | Required | Default | Description                                                                                       |
-|---------------------|----------|---------|---------------------------------------------------------------------------------------------------|
-| `GITHUB_USER_TOKEN` | false    | `''`    | Authentication token with write permission needed by the release bot (falls back to GITHUB_TOKEN) |
+| Name                         | Required | Default | Description                                                                                         |
+|------------------------------|----------|---------|-----------------------------------------------------------------------------------------------------|
+| `NPM_REGISTRY_TOKEN`         | false    | `''`    | Authentication for the private npm registry                                                         |
+| `GITHUB_USER_EMAIL`          | false    | `''`    | Email address for the GitHub user configuration                                                     |
+| `GITHUB_USER_NAME`           | false    | `''`    | Username for the GitHub user configuration                                                          |
+| `GITHUB_USER_SSH_KEY`        | false    | `''`    | Private SSH key associated with the GitHub user for the token passed as `GITHUB_USER_TOKEN`         |
+| `GITHUB_USER_SSH_PUBLIC_KEY` | false    | `''`    | Public SSH key associated with the GitHub user for the token passed as `GITHUB_USER_TOKEN`          |
+| `GITHUB_USER_TOKEN`          | false    | `''`    | Authentication token with write permission needed by the release bot (falls back to `GITHUB_TOKEN`) |
 
 **Example with configuration parameters:**
 
@@ -61,5 +72,25 @@ jobs:
   release:
     uses: inpsyde/reusable-workflows/.github/workflows/automatic-release.yml@main
     secrets:
-      GITHUB_USER_TOKEN: ${{ secrets.WRITE_TOKEN }}
+      GITHUB_USER_TOKEN: ${{ secrets.DEPLOYBOT_REPO_READ_WRITE_TOKEN }}
+```
+
+**Example with custom GitHub user and signed commits using SSH key:**
+
+```yml
+name: Release
+on:
+  push:
+    branches:
+      - main
+      - alpha
+jobs:
+  release:
+    uses: inpsyde/reusable-workflows/.github/workflows/automatic-release.yml@main
+    secrets:
+      GITHUB_USER_EMAIL: ${{ secrets.DEPLOYBOT_EMAIL }}
+      GITHUB_USER_NAME: ${{ secrets.DEPLOYBOT_USER }}
+      GITHUB_USER_SSH_KEY: ${{ secrets.DEPLOYBOT_SSH_PRIVATE_KEY }}
+      GITHUB_USER_SSH_PUBLIC_KEY: ${{ secrets.DEPLOYBOT_SSH_PUBLIC_KEY }}
+      GITHUB_USER_TOKEN: ${{ secrets.DEPLOYBOT_REPO_READ_WRITE_TOKEN }}
 ```