Checkpoint Lab — Artifacts, Retention, Cross-Job Data, and Workflow Result Management

1. Checkpoint scenario and invariant

You own a disposable repository gha-artifact-checkpoint. One job creates a tiny build manifest and uploads it. A second job must consume exactly that artifact and prove its content came from the current source SHA. The first run is intentionally broken by a name mismatch. You preserve the failure, repair the workflow to pass the artifact ID explicitly, rerun, verify digest/content/retention metadata, then optionally delete only the repaired lab artifact.

Delivery invariant: a downstream job may accept build evidence only when artifact identity, producing run/SHA, integrity and retention metadata all reconcile.

2. Current assumptions and preflight

Before running, predict: (1) the producer creates exactly one artifact record with a unique ID/digest tied to the run; (2) the intentionally broken consumer fails despite the artifact existing because it requests the wrong name; (3) after repair, the consumer downloads the exact ID and the extracted file SHA equals the producer's file SHA; (4) optional cleanup deletes the artifact record only after evidence is captured.

3. Attempt 1 — intentionally broken name selection

name: artifact-checkpoint
on:
  workflow_dispatch:
permissions: {}

jobs:
  build:
    runs-on: ubuntu-24.04
    outputs:
      artifact_id: ${{ steps.upload.outputs.artifact-id }}
      artifact_digest: ${{ steps.upload.outputs.artifact-digest }}
      file_sha256: ${{ steps.hash.outputs.sha256 }}
    steps:
      - name: Create build manifest
        shell: bash
        run: |
          mkdir -p dist
          printf 'sha=%s
run=%s
attempt=%s
'             "$GITHUB_SHA" "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" > dist/manifest.txt
      - id: hash
        shell: bash
        run: |
          sha="$(sha256sum dist/manifest.txt | awk '{print $1}')"
          echo "sha256=$sha" >> "$GITHUB_OUTPUT"
      - id: upload
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: manifest-${{ github.run_id }}
          path: dist/manifest.txt
          if-no-files-found: error
          retention-days: 1
          include-hidden-files: false

  consume:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - name: Broken selection — preserve this failure
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: manifest
          path: ${{ runner.temp }}/incoming

Do not “fix” Attempt 1 by renaming the artifact in the UI or deleting/re-uploading it. Save the run ID, attempt, head SHA, producer logs, upload artifact ID/digest, and the consumer's not-found selection error.

4. Repair — consume the artifact identity, not a naming assumption

Keep the producer unchanged. Replace the consumer with ID-based selection and explicit verification. Add a metadata inspection step with only actions: read.

consume:
    needs: build
    runs-on: ubuntu-24.04
    permissions:
      actions: read
    env:
      GH_TOKEN: ${{ github.token }}
      ARTIFACT_ID: ${{ needs.build.outputs.artifact_id }}
      UPLOAD_DIGEST: ${{ needs.build.outputs.artifact_digest }}
      EXPECTED_FILE_SHA: ${{ needs.build.outputs.file_sha256 }}
    steps:
      - name: Download by exact artifact ID
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          artifact-ids: ${{ needs.build.outputs.artifact_id }}
          path: ${{ runner.temp }}/incoming
          digest-mismatch: error

      - name: Verify source/content
        shell: bash
        run: |
          file="$RUNNER_TEMP/incoming/manifest.txt"
          test -f "$file"
          grep -Fx "sha=$GITHUB_SHA" "$file"
          actual="$(sha256sum "$file" | awk '{print $1}')"
          test "$actual" = "$EXPECTED_FILE_SHA"

      - name: Record GitHub artifact metadata
        shell: bash
        run: |
          gh api             -H 'X-GitHub-Api-Version: 2026-03-10'             "repos/$GITHUB_REPOSITORY/actions/artifacts/$ARTIFACT_ID"             --jq '{id,name,size_in_bytes,digest,expired,created_at,expires_at,workflow_run}'

5. Optional cleanup after evidence retention

After the repaired run is verified and the evidence packet is copied, you may add a separate manual/boolean-gated cleanup job with actions: write. It must delete only the exact artifact ID received from the producer.

cleanup:
  if: ${{ inputs.delete_after && needs.consume.result == 'success' }}
  needs: [build, consume]
  runs-on: ubuntu-24.04
  permissions:
    actions: write
  env:
    GH_TOKEN: ${{ github.token }}
    ARTIFACT_ID: ${{ needs.build.outputs.artifact_id }}
  steps:
    - shell: bash
      run: |
        test -n "$ARTIFACT_ID"
        gh api --method DELETE           -H 'X-GitHub-Api-Version: 2026-03-10'           "repos/$GITHUB_REPOSITORY/actions/artifacts/$ARTIFACT_ID"

If your workflow does not define delete_after, perform cleanup through the Actions UI or an explicitly authorized local gh api command instead. Cleanup is not part of the correctness proof.

6. Prediction and reconciliation table

7. Required evidence packet

8. Free/local faithful simulation

If Actions is unavailable, simulate the transport contract locally: create manifest.txt, compute SHA-256, copy it into an ID-named temporary directory, persist a JSON metadata record containing fake artifact ID/run/SHA/expiry, copy the file into a fresh consumer directory, and compare hashes. This proves the architecture of explicit identity + durable file transport, but it does not validate GitHub artifact service IDs, retention enforcement, action digest behavior or API permissions. Record those limitations.

9. Cleanup and rollback

Delete only disposable resources. If the artifact remains, let one-day retention expire or delete its exact ID after saving evidence. Delete the throwaway repository when finished. No external deployment, package, cloud resource, self-hosted runner or real credential exists, so there is no hidden infrastructure rollback.

10. What Chapter 13 adds to the operating model

You can now treat files as governed run outputs: the producer and source revision are recorded, the artifact has a service identity and digest, consumers select an exact record, retention/sensitivity are deliberate, and cleanup happens after evidence rather than instead of evidence. Chapter 14 turns to Dependency Caching, Cache Keys, Restore Strategies, and Performance—a deliberately different persistence mechanism optimized for speed rather than provenance.

Knowledge check

Official references and version notes

• GitHub Docs — Workflow artifacts — artifact purpose, cache distinction and attestation context.
• GitHub Docs — Store and share data with workflow artifacts — upload/download, retention, cross-job transfer and digest validation.
• GitHub REST API — Actions artifacts — artifact ID, size, digest, expiration, download and delete endpoints.
• actions/upload-artifact v7.0.1 — upload action pinned to 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a.
• actions/download-artifact v8.0.1 — download action pinned to 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c.
• GitHub Docs — Artifact attestations — signed provenance is separate from ordinary artifact storage/digest verification.