Checkpoint Lab — Workflow Templates, Organization Standards, YAML Anchors, and Reuse Architecture

1. Scenario and success contract

You are the platform engineer for a small organization. New repositories should receive a readable workflow wrapper from a golden-path template. The wrapper delegates real CI implementation to a maintained reusable workflow. Repository teams may customize triggers and local metadata, but the CI implementation should be versioned independently. A green run is not enough: your dossier must prove source identities and change semantics.

Mandatory free path: use one learner-owned disposable repository plus a local simulated-org-dot-github directory. The consumer calls a same-repository reusable workflow with $/, which resolves to the exact caller commit. Optional cross-repository extension: use two learner-owned disposable public repositories and paste the central reusable workflow's actual full SHA into the caller.

2. Predict state changes before execution

Write these predictions before creating Run A:

1. Copying the template creates a consumer-owned file; later edits to the simulated template source will not change that file.
2. The same-repository $/ call resolves the reusable workflow from the exact commit of the caller run.
3. Revision A passes an unsupported profile, so the reusable workflow's validation job fails before any deployment/external side effect.
4. Revision B changes only the caller input to a supported profile and should succeed without broader permissions.

Your evidence packet must mark each prediction confirmed or disproved.

3. Package layout

simulated-org-dot-github/
└── workflow-templates/
    ├── golden-path.yml
    └── golden-path.properties.json

.github/
└── workflows/
    ├── golden-contract.yml
    └── golden-path.yml     # copied/onboarded consumer wrapper

ci/
└── verify.sh

The copied wrapper and reusable contract intentionally live in different logical layers even in the one-repository simulation. The optional extension moves golden-contract.yml to a second public disposable repository and pins it by full SHA.

4. Create the central reusable contract

# .github/workflows/golden-contract.yml
name: chapter18-golden-contract
on:
  workflow_call:
    inputs:
      profile:
        description: Supported contract profile
        required: true
        type: string
    outputs:
      contract_version:
        description: Reviewed contract version
        value: ${{ jobs.verify.outputs.version }}
permissions: {}

jobs:
  verify:
    runs-on: ubuntu-24.04
    outputs:
      version: ${{ steps.result.outputs.version }}
    steps:
      - name: Validate interface
        shell: bash
        env:
          PROFILE: ${{ inputs.profile }}
        run: |
          set -euo pipefail
          case "$PROFILE" in
            baseline|strict) ;;
            *) echo "unsupported profile: $PROFILE" >&2; exit 64 ;;
          esac

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - id: result
        shell: bash
        env:
          PROFILE: ${{ inputs.profile }}
        run: |
          bash ci/verify.sh "$PROFILE"
          echo "version=golden-contract-v1" >> "$GITHUB_OUTPUT"

#!/usr/bin/env bash
# ci/verify.sh
set -euo pipefail
profile="${1:?profile required}"
printf 'profile=%s
' "$profile"
printf 'source_sha=%s
' "${GITHUB_SHA:-local}"
printf 'run=%s attempt=%s
' "${GITHUB_RUN_ID:-local}" "${GITHUB_RUN_ATTEMPT:-local}"

No secret, artifact, release, package, environment, cloud account, or write permission is needed.

5. Create the golden-path template source

# simulated-org-dot-github/workflow-templates/golden-path.yml
name: chapter18-golden-path
on:
  push:
    branches: [ $default-branch ]
  workflow_dispatch:
    inputs:
      profile:
        description: baseline or strict
        required: true
        default: baseline
        type: choice
        options: [baseline, strict]
permissions: {}

jobs:
  contract:
    uses: $/.github/workflows/golden-contract.yml
    with:
      profile: ${{ inputs.profile || 'baseline' }}

  evidence: &evidence_job
    needs: contract
    runs-on: ubuntu-24.04
    steps:
      - shell: bash
        env:
          VERSION: ${{ needs.contract.outputs.contract_version }}
        run: |
          echo "contract=$VERSION"
          echo "run=$GITHUB_RUN_ID attempt=$GITHUB_RUN_ATTEMPT sha=$GITHUB_SHA"

  evidence-copy: *evidence_job

{
  "name": "Chapter 18 Golden Path",
  "description": "Thin caller for the versioned CI contract.",
  "iconName": "octicon shield-check",
  "categories": ["Continuous integration"]
}

The anchor is intentionally confined to identical read-only evidence jobs. It does not hide deployment or permission differences.

6. Onboard the disposable consumer

mkdir -p .github/workflows
cp simulated-org-dot-github/workflow-templates/golden-path.yml .github/workflows/golden-path.yml
DEFAULT_BRANCH=$(git branch --show-current)
sed -i "s/\$default-branch/${DEFAULT_BRANCH}/g" .github/workflows/golden-path.yml

git add .github/workflows/golden-path.yml .github/workflows/golden-contract.yml ci/verify.sh simulated-org-dot-github/
git commit -m "chapter18: onboard golden path"
git rev-parse HEAD
sha256sum simulated-org-dot-github/workflow-templates/golden-path.yml .github/workflows/golden-path.yml

Record the onboarding commit SHA. The two file hashes may differ because $default-branch was substituted; that difference is expected and should be documented rather than “fixed.”

7. Revision A — intentionally break the interface

For Revision A only, change the copied consumer caller input/default to profile: legacy (or manually dispatch with an unsupported value if you temporarily model it as a string input in the disposable lab). Commit the change and start one run. Preserve the run ID, attempt, source SHA, and validation failure before editing anything.

Expected first failure
job: contract / verify
step: Validate interface
message: unsupported profile: legacy
side effects: none beyond GitHub run/log records
permissions: {}

Do not widen permissions, alter the runner, or change the reusable workflow to accept arbitrary strings. The contract is correctly rejecting an unsupported interface value.

8. Revision B — repair only the caller contract

Change only the consumer profile to baseline, commit, and rerun from the new revision. Expected evidence:

• contract succeeds and outputs golden-contract-v1.
• Both anchor-derived evidence jobs run independently on GitHub-hosted runners.
• Run ID/attempt/source SHA are printed without secrets.
• No artifact/cache/deployment/external target is created.

Preserve both Run A and Run B. They prove that the repair was an interface correction rather than a hidden permission or infrastructure change.

9. Prove copied versus centrally controlled behavior

After Run B, edit only simulated-org-dot-github/workflow-templates/golden-path.yml to change its displayed name to chapter18-golden-path-v2. Do not copy it again. Verify:

git diff -- simulated-org-dot-github/workflow-templates/golden-path.yml .github/workflows/golden-path.yml
sha256sum simulated-org-dot-github/workflow-templates/golden-path.yml .github/workflows/golden-path.yml

The consumer remains on its copied wrapper. By contrast, edit .github/workflows/golden-contract.yml and commit only after the lab evidence is complete: callers using same-repo $/ at a new caller commit resolve the new contract in that exact commit. In a cross-repository extension, a caller pinned to the old central SHA remains on v1 until the reference changes.

10. Optional cross-repository release strategy

For a production-like organization architecture, store the reusable contract in YOUR-ORG/gha-golden-path, review a release commit, and record:

CENTRAL_SHA=$(git rev-parse HEAD)
printf 'v1.0.0 -> %s
' "$CENTRAL_SHA"

The onboarded consumer should then contain a literal reference such as:

uses: YOUR-ORG/gha-golden-path/.github/workflows/golden-contract.yml@0123456789abcdef0123456789abcdef01234567

Replace the illustrative value with the actual reviewed 40-character commit SHA. The release tag is the human mapping; the SHA is the immutable execution identity. If the central repository is private/internal, configure only the necessary Actions access and respect current visibility rules—do not expose it publicly just for the lab.

11. Required security/operations dossier

12. Cleanup and rollback

• Delete the learner-owned disposable repository only after saving the dossier you want to keep.
• Remove local simulated-org-dot-github files if they are not part of your committed lab.
• If you used a second disposable public repository, delete it after recording its release SHA mapping.
• If you used an authorized disposable organization .github repository, remove only the exact lab template files you created. Do not alter unrelated organization templates or Actions policy.

No credential revocation is required because the mandatory lab creates none. If you chose an optional private-repository experiment with access changes, restore the exact prior access setting as part of cleanup.

13. Production operating model added by Chapter 18

You can now describe a golden path as a layered contract: templates distribute visible repository-owned wrappers, anchors reduce strictly local repetition, actions/reusable workflows centralize reviewed executable behavior, immutable references make rollout/rollback explicit, and policy constrains allowed sources. Evidence identifies each layer separately instead of claiming “the template is the pipeline.”

Knowledge check

Official references and version notes

Platform assumptions in this lesson were rechecked on 2026-09-10. GitHub Actions changes continuously, so re-verify version-sensitive behavior before production rollout.

• GitHub Docs — Reusing workflow configurations
• GitHub Docs — Creating workflow templates for your organization
• GitHub Docs — Reuse workflows
• GitHub Docs — Managing GitHub Actions settings for a repository
• GitHub Changelog — YAML anchors and non-public workflow templates
• GitHub Changelog — self-repository $/ syntax