Checkpoint Lab — Reusable Workflows, workflow_call, Inputs, Secrets, Outputs, and Nesting

1. Checkpoint scenario and invariant

Your repository has two entry points that should share one CI policy. The invariant is: callers choose only supported typed inputs, explicitly delegate one synthetic secret and at most contents: read, the central contract validates its interface, the nested leaf receives the secret only through explicit forwarding, and outputs contain no secret material.

Caller A represents the supported path. Caller B first violates the semantic runtime contract with 3.12. The failure must remain in Actions history. The repaired Caller B changes only that input to 3.13.

2. Preflight and assumptions

• GitHub.com disposable repository: gha-reuse-checkpoint.
• One synthetic repository secret: CH16_FAKE_SECRET; never use a real token.
• GitHub-hosted ubuntu-24.04; no self-hosted runner, cloud, registry or Kubernetes.
• No Marketplace or third-party actions; all work is shell plus same-repository reusable workflows.
• All four workflow files are committed together so relative reusable calls resolve from the same source SHA.
• Top-level callers default to permissions: {} and grant only contents: read to the central call job.

3. Contract files

Use the reusable-leaf.yml and reusable-ci.yml definitions from Lesson 2 unchanged. Their critical contract is reproduced below in compact form so the checkpoint is independently runnable.

# .github/workflows/reusable-leaf.yml
name: chapter16-reusable-leaf
on:
  workflow_call:
    inputs:
      channel: {required: true, type: string}
    secrets:
      probe_secret: {required: true}
    outputs:
      leaf_summary:
        value: ${{ jobs.probe.outputs.summary }}
permissions: {}
jobs:
  probe:
    runs-on: ubuntu-24.04
    outputs:
      summary: ${{ steps.result.outputs.summary }}
    steps:
      - id: result
        shell: bash
        env:
          CHANNEL: ${{ inputs.channel }}
          PROBE_SECRET: ${{ secrets.probe_secret }}
        run: |
          set -euo pipefail
          test -n "$PROBE_SECRET"
          case "$CHANNEL" in strict|relaxed) ;; *) exit 21 ;; esac
          printf 'summary=leaf-%s-secret-present
' "$CHANNEL" >> "$GITHUB_OUTPUT"

# .github/workflows/reusable-ci.yml
name: chapter16-reusable-ci
on:
  workflow_call:
    inputs:
      runtime: {required: true, type: string}
      strict: {required: false, default: true, type: boolean}
    secrets:
      demo_secret: {required: true}
    outputs:
      contract_result:
        value: ${{ jobs.contract.outputs.result }}
      leaf_summary:
        value: ${{ jobs.leaf.outputs.leaf_summary }}
permissions:
  contents: read
jobs:
  contract:
    runs-on: ubuntu-24.04
    outputs:
      result: ${{ steps.check.outputs.result }}
    steps:
      - id: check
        shell: bash
        env:
          RUNTIME: ${{ inputs.runtime }}
          STRICT: ${{ inputs.strict }}
          DEMO_SECRET: ${{ secrets.demo_secret }}
        run: |
          set -euo pipefail
          echo "repository=$GITHUB_REPOSITORY sha=$GITHUB_SHA"
          echo "run=$GITHUB_RUN_ID attempt=$GITHUB_RUN_ATTEMPT"
          echo "called_path=.github/workflows/reusable-ci.yml"
          test -n "$DEMO_SECRET"
          if [[ "$RUNTIME" != "3.13" ]]; then
            echo "unsupported runtime: $RUNTIME; contract supports 3.13" >&2
            exit 23
          fi
          printf 'result=runtime-%s-strict-%s
' "$RUNTIME" "$STRICT" >> "$GITHUB_OUTPUT"
  leaf:
    needs: contract
    permissions: {}
    uses: ./.github/workflows/reusable-leaf.yml
    with:
      channel: ${{ inputs.strict && 'strict' || 'relaxed' }}
    secrets:
      probe_secret: ${{ secrets.demo_secret }}

4. Caller A — supported baseline

# .github/workflows/caller-a.yml
name: chapter16-checkpoint-a
on: workflow_dispatch
permissions: {}
jobs:
  ci:
    permissions:
      contents: read
    uses: ./.github/workflows/reusable-ci.yml
    with:
      runtime: '3.13'
      strict: true
    secrets:
      demo_secret: ${{ secrets.CH16_FAKE_SECRET }}
  report:
    needs: ci
    permissions: {}
    runs-on: ubuntu-24.04
    steps:
      - shell: bash
        env:
          CONTRACT_RESULT: ${{ needs.ci.outputs.contract_result }}
          LEAF_SUMMARY: ${{ needs.ci.outputs.leaf_summary }}
        run: |
          echo "contract_result=$CONTRACT_RESULT"
          echo "leaf_summary=$LEAF_SUMMARY"

Run Caller A first. Record its run ID, attempt and source SHA. Expected safe outputs are runtime-3.13-strict-true and leaf-strict-secret-present.

5. Caller B Revision A — deliberate interface failure

# .github/workflows/caller-b.yml — Revision A
name: chapter16-checkpoint-b
on: workflow_dispatch
permissions: {}
jobs:
  ci:
    permissions:
      contents: read
    uses: ./.github/workflows/reusable-ci.yml
    with:
      runtime: '3.12'   # deliberate semantic incompatibility
      strict: false
    secrets:
      demo_secret: ${{ secrets.CH16_FAKE_SECRET }}
  report:
    needs: ci
    permissions: {}
    runs-on: ubuntu-24.04
    steps:
      - run: echo "This should not run because ci failed."

Commit Revision A and run Caller B. Predict that GitHub can create the run because 3.12 is a valid string, the central contract job starts, verifies that the fake secret is present, then exits 23 with unsupported runtime: 3.12; contract supports 3.13. The nested leaf and report jobs should not execute because their dependencies did not succeed.

Preserve this run. Do not re-run it blindly and do not change permissions or the secret. Record the failure before repairing the caller.

6. Caller B Revision B — least destructive repair

# Change exactly one contract value
with:
  runtime: '3.13'
  strict: false

Commit only that input correction and run Caller B again as a new workflow run. Expected safe outputs are runtime-3.13-strict-false and leaf-relaxed-secret-present. The central and leaf workflow implementation did not need modification.

7. Required state predictions and independent verification

8. Evidence packet

9. Verification checklist

• All workflow files are under .github/workflows and callers invoke reusable workflows at the job level.
• Caller A succeeds before the broken Caller B experiment.
• Broken Caller B preserves a real run, exact source SHA and first-failure message.
• The broken run does not execute the nested leaf or report job.
• Repaired Caller B changes only runtime: '3.12' to '3.13'.
• Search all three run logs for the literal fake secret value; it is absent.
• Central and leaf outputs contain fixed non-sensitive labels only.
• No workflow uses secrets: inherit, write-all permissions, mutable external reusable refs or external deployment resources.

10. Cleanup and rollback

Delete the repository secret CH16_FAKE_SECRET, then delete the throwaway repository when you have recorded the non-sensitive evidence you need. There is no package, release, artifact, cache, cloud resource, environment or runner registration to delete.

If you accidentally used a real credential despite the lab instructions, deleting the workflow/repository is not sufficient remediation. Revoke or rotate the external credential at its authority source and review logs/audit evidence.

11. What Chapter 16 adds to the operating model

You can now treat reusable workflows as explicit, versioned automation contracts: caller identity and trust remain visible; inputs and outputs are typed interfaces; secrets cross only named boundaries; permissions do not escalate; runner access follows caller context; and nested call chains are evidence that can be reviewed and diagnosed. Chapter 17 moves one layer down to Composite Actions, JavaScript Actions, Docker Actions, and Custom Automation, where reuse happens inside individual job steps rather than by delegating whole job graphs.

Knowledge check

Official references and version notes

• GitHub Docs — reuse workflows — workflow_call, typed inputs, secrets, outputs, nesting and matrix callers.
• GitHub Docs — reusing workflow configurations — access rules, current limits, supported caller-job keywords, runner behavior, permissions and rerun semantics.
• GitHub Docs — workflow syntax: on.workflow_call — input, secret and workflow-output contract syntax.
• GitHub Docs — jobs.<job_id>.uses — same-repository and cross-repository reusable-workflow references.
• GitHub Docs — re-run workflows and jobs — run-attempt identity and rerun behavior.
• GitHub Docs — use secrets — secret availability and reusable-workflow propagation boundaries.