Integration branches: plan-generated, verified, built to GHCR, cross-referenced on the PRs

.github/workflows/docker-build-push.yml

@@ -154,10 +154,21 @@ on:
         type: boolean
         required: false
         default: false
+      target:
+        description: 'Dockerfile build target (docker build --target); empty builds the last stage'
+        type: string
+        required: false
+        default: ''
+    outputs:
+      digest:
+        description: 'Digest of the pushed image (sha256:...); empty when nothing was pushed'
+        value: ${{ jobs.build-and-push.outputs.digest }}
 
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
     # Trust gate: run automatically for pushes, tags, dispatches, and same-repo PRs.
     # Fork PRs require the 'safe-to-build' label (only org members can apply it).
     # Fork PRs NEVER get images pushed, even with push-pr-images enabled.
@@ -259,6 +270,7 @@ jobs:
           tags: ${{ steps.dispatch-tag.outputs.tags || steps.meta-custom.outputs.tags || steps.meta-standard.outputs.tags }}
           labels: ${{ steps.meta-custom.outputs.labels || steps.meta-standard.outputs.labels }}
           build-args: ${{ inputs.build-args }}
+          target: ${{ inputs.target }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
@@ -274,6 +286,7 @@ jobs:
           load: true
           tags: ${{ inputs.image-name }}:trivy-scan
           build-args: ${{ inputs.build-args }}
+          target: ${{ inputs.target }}
           cache-from: type=gha
 
       - name: Determine Trivy scan target

.github/workflows/integration-build.yml

@@ -0,0 +1,101 @@
+# Reusable workflow: build and publish an integration branch ("bag of PRs") - but only if it verifies.
+# https://github.com/sirosfoundation/.github  (docs/integration-branches.md)
+#
+# An integration/<name> branch is generated from .integration/plan.yaml. This workflow:
+#   1. verifies the branch against its plan (a hand edit, patch or hidden change fails the build); glue is classified
+#      (resolution-only vs new code) in the log
+#   2. builds and pushes ghcr.io/<image-name>:<branch>-<sha7> through docker-build-push.yml (Buildx, Trivy, cache)
+#   (Cross-reference comments on the participating PRs are a follow-up, deliberately not part of this version.)
+#
+# Images contain UNMERGED code: never `latest`, pin consumers by DIGEST, re-pin to a release when the PRs land.
+#
+# Usage (see workflow-templates/integration.yml):
+#
+#   on:
+#     push:
+#       branches: ['integration/**']
+#   jobs:
+#     integration:
+#       uses: sirosfoundation/.github/.github/workflows/integration-build.yml@main
+#       permissions:
+#         contents: read
+#         packages: write
+#         security-events: write
+#       with:
+#         image-name: sirosfoundation/integration/my-service
+name: Build Integration Branch
+
+on:
+  workflow_call:
+    inputs:
+      image-name:
+        description: 'GHCR image name without registry prefix (e.g. sirosfoundation/integration/vc-apigw)'
+        type: string
+        required: true
+      dockerfile:
+        type: string
+        required: false
+        default: './Dockerfile'
+      context:
+        type: string
+        required: false
+        default: '.'
+      build-args:
+        description: 'Docker build arguments (multiline KEY=VALUE)'
+        type: string
+        required: false
+        default: ''
+      target:
+        description: 'Dockerfile build target'
+        type: string
+        required: false
+        default: ''
+      platforms:
+        type: string
+        required: false
+        default: 'linux/amd64'
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Verify the branch against its plan
+        uses: sirosfoundation/.github/actions/integration@main
+        with:
+          command: verify
+          args: --tip HEAD
+          token: ${{ github.token }}
+
+      - name: Tag
+        id: tag
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          SLUG=$(echo "$REF_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g')
+          echo "tag=${SLUG}-$(git rev-parse --short=7 HEAD)" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: verify
+    permissions:
+      contents: read
+      packages: write
+      security-events: write
+    uses: sirosfoundation/.github/.github/workflows/docker-build-push.yml@main
+    with:
+      image-name: ${{ inputs.image-name }}
+      dockerfile: ${{ inputs.dockerfile }}
+      context: ${{ inputs.context }}
+      build-args: ${{ inputs.build-args }}
+      target: ${{ inputs.target }}
+      platforms: ${{ inputs.platforms }}
+      custom-ref: ${{ github.ref }}
+      custom-tag: ${{ needs.verify.outputs.tag }}

.github/workflows/integration-tests.yml

@@ -0,0 +1,29 @@
+name: Integration tool tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'actions/integration/**'
+      - '.github/workflows/integration-*.yml'
+      - '.github/workflows/docker-build-push.yml'
+  pull_request:
+    paths:
+      - 'actions/integration/**'
+      - '.github/workflows/integration-*.yml'
+      - '.github/workflows/docker-build-push.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: python3 -m pip install --quiet pyyaml
+      - run: python3 -m unittest discover -s actions/integration/tests -v
+      - name: actionlint
+        run: |
+          bash <(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.7/scripts/download-actionlint.bash) 1.7.7
+          ./actionlint -color .github/workflows/integration-build.yml .github/workflows/integration-tests.yml .github/workflows/docker-build-push.yml

README.md

@@ -4,4 +4,8 @@ This repository contains organization-wide GitHub configuration files that are u
 
 ## Changes to this repo
 
-Since changes here show up across every repo (unless they've set up their own templates), any changes here should be **well discussed and approved** before merging. 
+Since changes here show up across every repo (unless they've set up their own templates), any changes here should be **well discussed and approved** before merging. 
+
+## Integration branches
+
+Testing several unmerged PRs together? See [docs/integration-branches.md](docs/integration-branches.md): plan-generated `integration/**` branches, verified, built to GHCR, with a cross-reference comment on every participating PR.

actions/integration/action.yml

@@ -0,0 +1,54 @@
+name: integration
+description: >
+  Integration branches ("bags of PRs"): sync, verify, report and comment. An integration/<name> branch is generated from
+  .integration/plan.yaml; verify proves nothing else is on it. See docs/integration-branches.md in sirosfoundation/.github.
+
+inputs:
+  command:
+    description: 'sync | verify | report | comment'
+    required: true
+  args:
+    description: 'Further arguments for integration.py (e.g. "--tip HEAD --summary")'
+    required: false
+    default: ''
+  path:
+    description: 'A clone of the repository holding the integration branch'
+    required: false
+    default: '.'
+  token:
+    description: 'GitHub token for the API (PR metadata, comments)'
+    required: false
+    default: ''
+
+outputs:
+  result:
+    description: 'stdout of the command'
+    value: ${{ steps.run.outputs.result }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install PyYAML
+      shell: bash
+      run: python3 -m pip install --quiet pyyaml
+
+    - name: integration.py
+      id: run
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        COMMAND: ${{ inputs.command }}
+        ARGS: ${{ inputs.args }}
+        REPO_PATH: ${{ inputs.path }}
+        ACTION_PATH: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+        # ARGS is split on whitespace on purpose (no quoting inside values); it comes from the calling workflow, not from users.
+        # shellcheck disable=SC2086
+        OUT=$(python3 "$ACTION_PATH/integration.py" "$COMMAND" --path "$REPO_PATH" --https $ARGS)
+        {
+          echo "result<<__INTEGRATION_EOF__"
+          echo "$OUT"
+          echo "__INTEGRATION_EOF__"
+        } >> "$GITHUB_OUTPUT"
+        echo "$OUT"