chore: refactor re-usable workflows to enable re-use in derived repositories

.github/instructions/workflows.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: ".github/workflows/*.yml"
+---
+
+# GitHub Workflows Guidelines
+
+When writing GitHub Action workflows, ensure that:
+
+- Workflows that have a workflow_call trigger have their filename prefixed with `wc-`.
+- For all re-usable workflows, only the top-level workflow (workflows that are not called themselves by other workflows with workflow_call) has defaults and descriptions for inputs to avoid duplication.
+- All workflows and action definitions have a name that is descriptive and concise, using emoji where appropriate.
+- The sorting order for inputs, secrets, and outputs is alphabetical.
+- The sorting order of other keys is consistent across the repository.

.github/workflows/continuous-integration.yml

@@ -1,5 +1,5 @@
 ---
-name: Continuous Integration
+name: CI
 
 on:
   merge_group:
@@ -14,6 +14,10 @@
 
 jobs:
   build-push-test:
+    name: 🛠️ Build → Push → Test (🍨 ${{ matrix.flavor }})
+    strategy:
+      matrix:
+        flavor: [cpp, rust]
     uses: ./.github/workflows/wc-build-push-test.yml
     secrets:
       TEST_GITHUB_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }}
@@ -28,3 +32,45 @@
       id-token: write
       packages: write
       pull-requests: write
+    with:
+      devcontainer-metadata-file: .devcontainer/${{ matrix.flavor }}/devcontainer-metadata.json
+      dockerfile: .devcontainer/${{ matrix.flavor }}/Dockerfile
+      image-name: ${{ github.repository }}-${{ matrix.flavor }}
+      integration-test-file: test/${{ matrix.flavor }}/integration-tests.bats
+      acceptance-test-path: ${{ matrix.flavor == 'cpp' && 'test/cpp/features' || '' }}
+      test-devcontainer-file: ${{ matrix.flavor == 'cpp' && '.devcontainer/cpp-test/devcontainer.json' || '' }}
+
+  dependency-review:
+    name: 🔍 Dependency Review
+    needs: build-push-test
+    uses: ./.github/workflows/wc-dependency-review.yml
+    permissions:
+      contents: read
+      pull-requests: write
+
+  publish-test-results:
+    name: 📊 Publish Test Results
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+      pull-requests: write
+    needs: build-push-test
+    if: ${{ !cancelled() }}
+    steps:
+      - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
+        with:
+          disable-sudo: true
+          egress-policy: audit
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          merge-multiple: true
+          pattern: test-results-*
+      - uses: EnricoMi/publish-unit-test-result-action@3a74b2957438d0b6e2e61d67b05318aa25c9e6c6 # v2.20.0
+        with:
+          files: test-report-*.xml
+
+  generate-documents:
+    name: 📄 Documentation
+    uses: ./.github/workflows/wc-document-generation.yml
+    permissions:
+      contents: read

.github/workflows/image-cleanup.yml

@@ -9,7 +9,8 @@ on:
 permissions: {}
 
 jobs:
-  delete-images:
+  cleanup-images:
+    name: 🧹 Clean Images
     runs-on: ubuntu-latest
     permissions:
       # dataaxiom/ghcr-cleanup-action needs packages write permission
@@ -19,7 +20,6 @@ jobs:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
           disable-sudo: true
-          egress-policy: block
           allowed-endpoints: >
             api.github.com:443
             ghcr.io:443

.github/workflows/issue-cleanup.yml

@@ -9,6 +9,7 @@ permissions: {}
 
 jobs:
   close-issues:
+    name: ♻️ Close Stale Issues & PRs
     runs-on: ubuntu-latest
     permissions:
       issues: write

.github/workflows/linting-formatting.yml

@@ -19,6 +19,7 @@ permissions:
 
 jobs:
   linter:
+    name: 🧹 Lint & Format
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/ossf-scorecard.yml

@@ -13,6 +13,7 @@ permissions: read-all
 
 jobs:
   ossf-scorecard:
+    name: 🛡️ OpenSSF Scorecard
     runs-on: ubuntu-latest
     permissions:
       security-events: write

.github/workflows/pr-conventional-title.yml

@@ -12,14 +12,14 @@ permissions: {}
 
 jobs:
   validate-pr-title:
+    name: ✅ Validate PR Title
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
           disable-sudo-and-containers: true
-          egress-policy: block
           allowed-endpoints: >
             api.github.com:443
       - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
@@ -33,7 +33,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
-        if: always() && steps.pr-title.outputs.error_message != null
+        if: ${{ !cancelled() && steps.pr-title.outputs.error_message != null }}
         with:
           header: pr-title-lint-error
           message: |

.github/workflows/pr-image-cleanup.yml

@@ -9,6 +9,7 @@ permissions: {}
 
 jobs:
   delete-images:
+    name: 🗑️ Delete PR Images
     runs-on: ubuntu-latest
     permissions:
       packages: write
@@ -22,6 +23,7 @@ jobs:
           delete-tags: pr-${{ github.event.pull_request.number }}
           packages: amp-devcontainer,amp-devcontainer-cpp,amp-devcontainer-rust
   cleanup-cache:
+    name: 🧹 Cleanup Cache
     runs-on: ubuntu-latest
     permissions:
       # actions: write permission is required to delete the cache

.github/workflows/pr-report.yml

@@ -9,6 +9,7 @@ permissions: {}
 
 jobs:
   add-pr-report:
+    name: 📊 Add PR Report
     permissions:
       contents: read
       checks: read

.github/workflows/release-build.yml

@@ -16,6 +16,10 @@ permissions: {}
 
 jobs:
   build-push-test:
+    name: Build, Push and Test (🍨 ${{ matrix.flavor }})
+    strategy:
+      matrix:
+        flavor: [cpp, rust]
     uses: ./.github/workflows/wc-build-push-test.yml
     secrets:
       TEST_GITHUB_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }}
@@ -30,7 +34,15 @@ jobs:
       id-token: write
       packages: write
       pull-requests: write
+    with:
+      devcontainer-metadata-file: .devcontainer/${{ matrix.flavor }}/devcontainer-metadata.json
+      dockerfile: .devcontainer/${{ matrix.flavor }}/Dockerfile
+      image-name: ${{ github.repository }}-${{ matrix.flavor }}
+      integration-test-file: test/${{ matrix.flavor }}/integration-tests.bats
+      acceptance-test-path: ${{ matrix.flavor == 'cpp' && 'test/cpp/features' || '' }}
+      test-devcontainer-file: ${{ matrix.flavor == 'cpp' && '.devcontainer/cpp-test/devcontainer.json' || '' }}
   apply-release-notes-template:
+    name: 📝 Apply Release Template
     runs-on: ubuntu-latest
     permissions:
       # `contents: write` is needed to modify a release.
@@ -57,6 +69,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           REF_NAME: ${{ github.ref_name }}
   update-release-notes:
+    name: Update Release Notes (🍨 ${{ matrix.flavor }})
     strategy:
       matrix:
         flavor: [cpp, rust]
@@ -108,6 +121,7 @@ jobs:
           GH_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ github.token }}
   upload-documents:
+    name: 📄 Upload Documents
     runs-on: ubuntu-latest
     permissions:
       # `contents: write` is needed to modify a release.
@@ -126,3 +140,4 @@ jobs:
         env:
           GH_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ github.token }}
+          REF_NAME: ${{ github.ref_name }}

.github/workflows/release-please.yml

@@ -14,6 +14,7 @@ permissions:
 
 jobs:
   create-release:
+    name: 🚀 Create Release
     runs-on: ubuntu-latest
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1

.github/workflows/social-interaction.yml

@@ -11,6 +11,7 @@ permissions: {}
 
 jobs:
   greeting:
+    name: 👋 First Interaction Greeting
     runs-on: ubuntu-latest
     permissions:
       issues: write
@@ -20,7 +21,6 @@ jobs:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
           disable-sudo-and-containers: true
-          egress-policy: block
           allowed-endpoints: >
             api.github.com:443
       - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # v3.1.0

.github/workflows/update-dependencies.yml

@@ -10,6 +10,7 @@ permissions: {}
 
 jobs:
   update-apt-dependencies:
+    name: Update APT Dependencies (🍨 ${{ matrix.flavor }})
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -45,11 +46,12 @@ jobs:
           token: ${{ steps.token.outputs.token }}
           sign-commits: true
   update-vscode-extensions:
+    name: Update VS Code Extensions (🍨 ${{ matrix.flavor }}, ${{ matrix.file }})
     runs-on: ubuntu-latest
     strategy:
       matrix:
         flavor: ["cpp", "rust"]
-        file: ["devcontainer-metadata-vscode.json", "devcontainer.json"]
+        file: ["devcontainer-metadata.json", "devcontainer.json"]
     permissions:
       contents: write
       pull-requests: write

.github/workflows/vulnerability-scan.yml

@@ -10,6 +10,7 @@ permissions: {}
 
 jobs:
   vulnerability-scan:
+    name: 🛡️ Vulnerability Scan (🍨 ${{ matrix.flavor }})
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/wc-acceptance-test.yml

@@ -4,7 +4,13 @@
 on:
   workflow_call:
     inputs:
-      flavor:
+      image-basename:
+        required: true
+        type: string
+      devcontainer-file:
+        required: true
+        type: string
+      acceptance-test-path:
         required: true
         type: string
     secrets:
@@ -26,11 +32,12 @@
 
 jobs:
   test:
+    name: Acceptance Test
     runs-on: ubuntu-latest
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
-          # Playwright requires root privileges to install browsers
+          disable-sudo: false # Playwright requires root privileges to install browsers
           egress-policy: audit
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
@@ -42,16 +49,16 @@
           set -Eeuo pipefail
 
           if [[ "${{ github.event_name }}" == "pull_request" ]]; then
             gh secret set -a codespaces IMAGE_VERSION --body "pr-${{ github.event.pull_request.number }}"
           elif [[ "${{ github.event_name }}" == "push" && "${{ startsWith(github.ref, 'refs/tags/') }}" == "true" ]]; then
             gh secret set -a codespaces IMAGE_VERSION --body "${GITHUB_REF#refs/tags/}"
           else
             gh secret set -a codespaces IMAGE_VERSION --body "edge"
           fi
 
-          echo CODESPACE_NAME="$(gh codespace create -R "${{ github.repository }}" -b "$HEAD_REF" -m basicLinux32gb --devcontainer-path ".devcontainer/${CONTAINER_FLAVOR}-test/devcontainer.json" --idle-timeout 10m --retention-period 1h)" >> "$GITHUB_ENV"
+          echo CODESPACE_NAME="$(gh codespace create -R "${{ github.repository }}" -b "$HEAD_REF" -m basicLinux32gb --devcontainer-path "${DEVCONTAINER_FILE}" --idle-timeout 10m --retention-period 1h)" >> "$GITHUB_ENV"
         env:
-          CONTAINER_FLAVOR: ${{ inputs.flavor }}
+          DEVCONTAINER_FILE: ${{ inputs.devcontainer-file }}
           GH_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }}
           HEAD_REF: ${{ github.head_ref }}
       - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
@@ -82,17 +89,17 @@
           done
         env:
           GH_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }}
-      - run: cd "test/${CONTAINER_FLAVOR}/features" && npm test
+      - run: cd "${ACCEPTANCE_TEST_PATH}" && npm test
         env:
-          CONTAINER_FLAVOR: ${{ inputs.flavor }}
+          ACCEPTANCE_TEST_PATH: ${{ inputs.acceptance-test-path }}
           GITHUB_USER: ${{ secrets.TEST_GITHUB_USER }}
           GITHUB_PASSWORD: ${{ secrets.TEST_GITHUB_PASSWORD }}
           GITHUB_TOTP_SECRET: ${{ secrets.TEST_GITHUB_TOTP_SECRET }}
-          PLAYWRIGHT_JUNIT_OUTPUT_NAME: ${{ github.workspace }}/test-report-acceptance-${{ inputs.flavor }}.xml
+          PLAYWRIGHT_JUNIT_OUTPUT_NAME: ${{ github.workspace }}/test-report-acceptance-${{ inputs.image-basename }}.xml
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        if: always()
+        if: ${{ !cancelled() }}
         with:
-          name: test-results-acceptance-${{ inputs.flavor }}
+          name: test-results-acceptance-${{ inputs.image-basename }}
           path: |
             test-report-*.xml
             test-results/