Checkpoint Lab — Self-Hosted Runners, Runner Groups, Isolation, and Operational Security

1. Checkpoint charter

2. Predict state changes before registration

1. After registration, GitHub will show one repository-scoped runner with default OS/architecture labels plus chapter09-lab.
2. When run.sh connects, status will become Idle; during the job it will become Active.
3. The trusted job will execute under the dedicated lab OS account, not a GitHub-hosted VM.
4. A synthetic file written under the lab account’s home will remain after the job until explicitly cleaned or the VM is destroyed.
5. After removal, GitHub routing identity will disappear; after VM wipe, local runner/workspace/credential state will disappear.

3. Setup and registration

Follow the exact account-generated package instructions in Settings → Actions → Runners → New self-hosted runner. Record the package hash and ./run.sh --version. Register only the disposable repository using a locally entered time-limited token:

read -rsp 'Runner registration token: ' RUNNER_REG_TOKEN; echo
./config.sh \
  --url https://github.com/OWNER/gha-runner-lab \
  --token "$RUNNER_REG_TOKEN" \
  --name ch09-checkpoint-01 \
  --labels chapter09-lab \
  --work _work \
  --unattended
unset RUNNER_REG_TOKEN
./run.sh

If the host contains any unexpected secret, personal SSH key, production mount or sensitive internal route, abort and rebuild the lab on cleaner compute.

4. Trusted checkpoint workflow

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

jobs:
  trusted-lab:
    runs-on: [self-hosted, linux, x64, chapter09-lab]
    steps:
      - name: Record safe execution identity
        shell: bash
        run: |
          set -euo pipefail
          printf 'runner=%s os=%s arch=%s\n' \
            '${{ runner.name }}' '${{ runner.os }}' '${{ runner.arch }}'
          printf 'run_id=%s attempt=%s sha=%s\n' \
            "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" "$GITHUB_SHA"
          id
          printf 'workspace=%s\n' "$GITHUB_WORKSPACE"

      - name: Create controlled residual state
        shell: bash
        run: |
          set -euo pipefail
          state="$HOME/.gha-ch09-checkpoint"
          mkdir -p "$state"
          printf 'run=%s\n' "$GITHUB_RUN_ID" > "$state/sentinel.txt"
          sha256sum "$state/sentinel.txt"

This is the only workload. It does not fetch repository code, invoke Docker, call external APIs or access secrets.

5. Inspect residual state and diagnostics

After the job completes, keep the runner stopped from accepting additional unrelated work while you inspect the lab:

test -f "$HOME/.gha-ch09-checkpoint/sentinel.txt"
wc -c "$HOME/.gha-ch09-checkpoint/sentinel.txt"
ls -1 _diag/Runner_*.log 2>/dev/null | tail -n 3
ls -1 _diag/Worker_*.log 2>/dev/null | tail -n 3
./run.sh --version

Record filenames, hashes and relevant non-sensitive diagnostic excerpts. Do not copy .credentials, registration tokens or whole environment dumps into the evidence packet.

6. Clean the controlled residue

rm -rf "$HOME/.gha-ch09-checkpoint"
test ! -e "$HOME/.gha-ch09-checkpoint" && echo 'lab_residue_removed=true'

This cleanup proves the synthetic file was removed. It does not prove a compromised persistent host is trustworthy. Production integrity should come from immutable/rebuilt compute, especially for one-job ephemeral/JIT designs.

7. Deregister and destroy the lab

Use the current runner removal flow in GitHub Settings, enter the generated token locally, and run the provided removal command. Verify the runner disappears from GitHub Settings. Retain reviewed evidence, then delete the runner installation directory and destroy or revert the disposable VM.

# Shape of the local removal command; use the token generated by GitHub.
read -rsp 'Runner removal token: ' RUNNER_REMOVE_TOKEN; echo
./config.sh remove --token "$RUNNER_REMOVE_TOKEN"
unset RUNNER_REMOVE_TOKEN

8. Evidence packet

9. Controls required before real organizational use

• Private/trusted source boundary; no public fork code on trusted self-hosted infrastructure.
• Runner groups with selected repository/workflow access where organization/enterprise sharing is used.
• Dedicated least-privilege service account; no ambient personal/admin credentials.
• Network segmentation and explicit destination policy.
• Ephemeral/JIT one-job compute for scalable production use where practical.
• Clean immutable image/bootstrap process and defined host/runner/tool update SLA.
• No unnecessary Docker socket or privileged host mounts.
• Externally retained Runner/Worker diagnostics for ephemeral fleets.
• Credential inventory, rotation/revocation and incident isolation/rebuild procedure.
• Capacity/queue monitoring with routing labels documented as capability, not trust.

10. Simulation-only completion path

If you used no real runner, your evidence packet must clearly say so. Simulate repository scope, runner status, labels, a one-job state file and teardown in a local directory, then explain which claims remain unverified: GitHub registration, live job routing, status transitions and actual runner diagnostics.

11. Chapter 09 production operating contract

Chapter 09 adds a self-hosted runner governance contract: runner scope and group authorization, job-source trust, least-privilege service identity, network reachability, persistent-state handling, runner/host patch ownership, external diagnostics, controlled cleanup and incident-safe rebuild are all part of CI/CD correctness—not infrastructure details outside the pipeline.

Chapter 10 moves to Runner Scale Sets, Actions Runner Controller, and Kubernetes Autoscaling, where the same trust and lifecycle rules must survive automated provisioning and fleet-scale scheduling.

Knowledge check

Official references and version notes

• Self-hosted runners concept — current responsibility boundary, hierarchy scopes, persistence model and maintenance ownership.
• Self-hosted runners reference — current supported operating systems/architectures, routing, communication, ephemeral/JIT guidance and update requirements.
• Adding self-hosted runners — current repository/organization/enterprise registration workflow and time-limited registration-token process.
• Using self-hosted runners in a workflow — current runs-on label/group selection semantics.
• Runner groups — runner groups as access-control boundaries and plan-dependent organization features.
• Managing access to self-hosted runners using groups — selected repository/workflow access policies and group governance.
• Secure use reference — current self-hosted runner hardening, public-repository warning, JIT guidance and trust-boundary risks.
• Compromised runners — current impact model for malicious workflow code, secrets, tokens and cross-repository credentials.
• Monitoring and troubleshooting self-hosted runners — current runner status, _diag Runner/Worker logs and update diagnostics.
• Configuring the runner as a service — current Linux/macOS/Windows service-mode procedures and status checks.
• Removing self-hosted runners — current deregistration/offline behavior, automatic stale-runner removal and local cleanup guidance.
• Actions Runner releases — public runner release history and progressive-release note.