docs/actions: add checkout canary

Status	File	+	-
A	`.shithub/workflows/checkout-canary.yml`	17	0
M	`bench/fixtures/README.md`	6	3
A	`bench/fixtures/actions/checkout-canary.yml`	13	0
M	`docs/internal/actions-runner-api.md`	30	21
M	`docs/internal/actions-schema.md`	13	6
M	`docs/internal/runbooks/actions-runner.md`	5	4
M	`docs/internal/runbooks/actions.md`	40	8
M	`docs/public/user/actions.md`	22	9

.shithub/workflows/checkout-canary.ymladded

 +name: checkout canary
 +on:
 +  push:
 +    branches: [trunk]
 +  workflow_dispatch:
 +jobs:
 +  checkout:
 +    runs-on: ubuntu-latest
 +    steps:
 +      - uses: actions/checkout@v4
 +      - name: Verify checkout
 +        env:
 +          EXPECTED_SHA: ${{ shithub.sha }}
 +        run: |
 +          test -f go.mod
 +          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
 +          bash scripts/lint-migration-versions.sh

bench/fixtures/README.mdmodified

  `actions/smoke-run-only.yml` is the canonical first end-to-end Actions
  workflow fixture. Copy it into `.shithub/workflows/smoke.yml` in a
 -repository with a registered `ubuntu-latest` runner. It intentionally uses only
 -`run:` steps because the current executor rejects reserved `uses:` aliases
 -until checkout and artifact execution are implemented.
 +repository with a registered `ubuntu-latest` runner.
++
 +`actions/checkout-canary.yml` is the next fixture once the run-only smoke is
 +green. It verifies `actions/checkout@v4` and pins that the runner workspace is
 +on the workflow run's exact `shithub.sha`. Artifact aliases remain reserved
 +until artifact execution is implemented.

bench/fixtures/actions/checkout-canary.ymladded

 +name: checkout canary
 +on: [push, workflow_dispatch]
 +jobs:
 +  checkout:
 +    runs-on: ubuntu-latest
 +    steps:
 +      - uses: actions/checkout@v4
 +      - name: Verify checkout
 +        env:
 +          EXPECTED_SHA: ${{ shithub.sha }}
 +        run: |
 +          test -f go.mod
 +          test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"

docs/internal/actions-runner-api.mdmodified

  has claims:
  ```json
 -{"sub":"runner:<id>","job_id":1,"run_id":1,"repo_id":1,"exp":0,"jti":"..."}
 +{"sub":"runner:<id>","purpose":"api","job_id":1,"run_id":1,"repo_id":1,"exp":0,"jti":"..."}
  ```
  The signing key is derived from `auth.totp_key_b64` with HKDF label
  `actions-runner-jwt-v1`; the raw TOTP/secretbox key is not used
  directly for JWT signing.
 -Job JWTs are single-use. Every job endpoint verifies the signature and
 -expiry, checks that the path job belongs to the claimed runner/run, and
 -then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
 -support multi-step runner flows, successful in-flight job endpoints
 -return `next_token` and `next_token_expires_at`.
 +API-purpose job JWTs are single-use. Every job endpoint verifies the
 +signature and expiry, checks that the path job belongs to the claimed
 +runner/run, and then inserts `jti` into `runner_jwt_used`. A replay
 +returns 401. To support multi-step runner flows, successful in-flight job
 +endpoints return `next_token` and `next_token_expires_at`.
  Consumed JWT rows are retained for 30 days after token expiry, then
  pruned by the daily `workflow:cleanup` worker. This keeps the replay
  grow unbounded.
  `shithubd-runner` consumes the same token chain: it claims with the
 -registration token, marks the job `running` with the first job JWT, then
 -uses each returned `next_token` serially for log chunks, step-status
 -updates, cancel checks, artifact upload requests, and finally the
 -terminal job-status update. Reusing any consumed job JWT is a replay and
 -must fail with 401.
 +registration token, marks the job `running` with the first API-purpose job
 +JWT, then uses each returned `next_token` serially for log chunks,
 +step-status updates, cancel checks, artifact upload requests, and finally
 +the terminal job-status update. Reusing any consumed API-purpose job JWT
 +is a replay and must fail with 401.
++
 +The heartbeat claim also returns `job.checkout_url` and
 +`job.checkout_token` for `actions/checkout@v4`. The checkout token is a
 +separate JWT with `purpose:"checkout"` and the same runner/job/run/repo
 +scope. It is intentionally reusable while the job is `running`, because
 +Git smart HTTP performs multiple Basic-authenticated requests during one
 +checkout. The git HTTP handler accepts it only for `git-upload-pack`, only
 +for the claimed repository, and only while the database still shows that
 +the claimed runner is running the job. It is never accepted for pushes or
 +runner API endpoints.
  ## Endpoints
  `token`, `expires_at`, and `job` when a job is claimed. Capacity is
  enforced server-side by counting current `workflow_jobs.status =
  'running'` rows for the runner while holding a row lock on the runner.
 -The job payload includes resolved `secrets` and `mask_values`; repo
 -secrets shadow org secrets with the same name. The server also stores
 -an encrypted claim-time copy of the mask values on
 -`workflow_job_secret_masks` so later log uploads are scrubbed against
 -the secrets that were actually handed to the runner, even if an
 +The job payload includes `checkout_url`, `checkout_token`, resolved
 +`secrets`, and `mask_values`; repo secrets shadow org secrets with the
 +same name. The server also stores an encrypted claim-time copy of the mask
 +values on `workflow_job_secret_masks` so later log uploads are scrubbed
 +against the secrets that were actually handed to the runner, even if an
  operator rotates or deletes a secret mid-job.
  `POST /api/v1/jobs/{id}/logs`
  job are marked cancelled too. This keeps a killed job from leaving queued
  step rows that the UI would otherwise treat as live.
 -S41d PR2 runner execution supports containerized `run:` steps with
 -per-step log streaming and server-side log finalization. `uses:` aliases
 -such as `actions/checkout@v4` and artifact upload/download remain
 -reserved for the later S41d slices that add checkout metadata and
 -artifact transfer.
 +Runner execution supports host-side `actions/checkout@v4` followed by
 +containerized `run:` steps with per-step log streaming and server-side log
 +finalization. Artifact upload/download aliases remain reserved until the
 +artifact transfer path lands.
  `POST /api/v1/jobs/{id}/artifacts/upload`

docs/internal/actions-schema.mdmodified

  | Alias                            | Parser status | Runner status                              |
  | -------------------------------- | ------------- | ------------------------------------------ |
 -| `actions/checkout@v4`            | accepted      | rejected until checkout support lands      |
 +| `actions/checkout@v4`            | accepted      | executable with scoped checkout token      |
  | `shithub/upload-artifact@v1`     | accepted      | rejected until artifact upload lands       |
  | `shithub/download-artifact@v1`   | accepted      | rejected until artifact download lands     |
  explicitly out of scope for v1; revisit only if a real demand exists
  and we have an answer for supply-chain trust.
 -The current Docker executor runs `run:` steps only. It fails a reserved
 -`uses:` alias deliberately instead of pretending checkout/artifact
 -semantics exist. This keeps the first end-to-end smoke path honest:
 -`run:`-only workflows are executable now, while repository checkout and
 -artifact transfer remain explicit follow-up work.
 +The current Docker executor runs `actions/checkout@v4` and `run:` steps.
 +Checkout happens on the runner host before a containerized step mounts the
 +workspace. The server issues a short-lived checkout-purpose JWT scoped to
 +the claimed repository and running job; the smart-HTTP handler accepts it
 +only for read-only `git-upload-pack`. Artifact transfer remains explicit
 +follow-up work, and the artifact aliases fail deliberately until that path
 +exists.
++
 +Checkout v1 accepts only `with.fetch-depth`. The default is a depth-1 fetch
 +of the workflow run's `head_sha`; `fetch-depth: 0` requests full history.
 +Submodules, LFS, `path`, persisted credentials, and marketplace actions are
 +rejected because they are not part of this dialect yet.
  ### File-size + parser caps

docs/internal/runbooks/actions-runner.mdmodified

  # Actions runner smoke runbook
  This runbook validates the runner-facing Actions path. `shithubd-runner`
 -now claims jobs and executes containerized `run:` steps through Docker or
 -Podman. The curl flow below remains useful for token/replay debugging.
 +now claims jobs, performs scoped `actions/checkout@v4`, and executes
 +containerized `run:` steps through Docker or Podman. The curl flow below
 +remains useful for token/replay debugging.
  For host provisioning and the systemd/Ansible path, see
  [runner-deploy.md](./runner-deploy.md).
  - Docker or Podman is installed on the runner host.
  - A repo has a workflow under `.shithub/workflows/*.yml` with
    `runs-on: ubuntu-latest`, and a push/dispatch has enqueued a run.
 -  S41d PR1 supports `run:` steps; checkout and artifact aliases land in
 -  the following S41d slices.
 +  Checkout and `run:` steps are executable; artifact aliases remain
 +  reserved until artifact transfer lands.
  `runs-on` is a runner-label selector, not a hard-coded image name.
  A workflow that says `runs-on: ubuntu-latest` can be claimed by any

docs/internal/runbooks/actions.mdmodified

  registered runner heartbeat claims a matching queued job
+         |
+         v
 -containerized run: steps -> log chunks -> step/job status -> run rollup
 +actions/checkout@v4 -> containerized run: steps
 +        |
 +        v
 +log chunks -> step/job status -> run rollup
  ```
 -The v1 executor supports containerized `run:` steps. The parser reserves
 -`actions/checkout@v4`, `shithub/upload-artifact@v1`, and
 -`shithub/download-artifact@v1`, but the Docker runner rejects `uses:` steps
 -until checkout metadata and artifact transfer are wired end to end. Do not use
 -`actions/checkout@v4` in production smoke workflows yet.
 +The v1 executor supports host-side `actions/checkout@v4` plus containerized
 +`run:` steps. The checkout token is short-lived, repository-scoped, tied to a
 +running job, and accepted only for read-only smart-HTTP fetches.
 +`shithub/upload-artifact@v1` and `shithub/download-artifact@v1` are still
 +reserved aliases and fail until artifact transfer is wired end to end.
  ## First smoke
  Repeat with `exit 1`; the check should complete with `failure`.
 +## Checkout smoke
++
 +After the run-only smoke passes, verify repository checkout with:
++
 +```yaml
 +name: checkout smoke
 +on: [push, workflow_dispatch]
 +jobs:
 +  checkout:
 +    runs-on: ubuntu-latest
 +    steps:
 +      - uses: actions/checkout@v4
 +      - run: test -f README.md
 +      - run: test "$(git rev-parse HEAD)" = "${{ shithub.sha }}"
 +```
++
 +Expected result:
++
 +- The claim response contains `checkout_url` and `checkout_token`.
 +- Git smart HTTP sees the checkout token as Basic auth and permits
 +  `git-upload-pack` for the claimed repo.
 +- `git-receive-pack` rejects the same credential with 403.
 +- The job workspace contains the exact `shithub.sha` commit before the first
 +  `run:` step starts.
++
  ## Live log tail
  Step log pages open an SSE stream at:
    capacity, then inspect runner journal output and heartbeat metrics.
  - **Step logs buffer:** verify the Caddy route above and confirm the SSE route
    is still mounted outside compression and short timeouts.
 -- **`uses:` step fails:** expected for now. Replace with a `run:` step until
 -  checkout/artifact support lands.
 +- **`actions/checkout@v4` fails:** confirm the job is still running, the repo
 +  URL in the runner claim points at this shithub instance, and the runner host
 +  can reach smart HTTP. The checkout token is not valid after the job leaves
 +  `running`.
 +- **Artifact `uses:` step fails:** expected for now. Replace with a `run:`
 +  step until artifact support lands.
  - **Secrets appear masked inconsistently:** check
    `shithub_actions_log_scrub_replacements_total{location="server"}` and confirm
    the job was claimed after the secret was created or rotated. Mask snapshots

docs/public/user/actions.mdmodified

  ## What works today
  - `push`, `pull_request`, `schedule`, and `workflow_dispatch` triggers
 +- `actions/checkout@v4` for repository checkout
  - `run:` steps executed in the operator-configured runner image
  - `runs-on:` label matching against registered runners
  - workflow, job, and step `env:`
  ## Current limit
 -Use `run:` steps for now. The parser accepts these reserved aliases:
 +The runner executes `actions/checkout@v4` and `run:` steps. Checkout accepts
 +the default shallow fetch and `with.fetch-depth`; use `fetch-depth: 0` when a
 +workflow needs full history:
++
 +```yaml
 +steps:
 +  - uses: actions/checkout@v4
 +    with:
 +      fetch-depth: "0"
 +  - run: git describe --tags --always
 +```
++
 +The parser also accepts these artifact aliases:
 -- `actions/checkout@v4`
  - `shithub/upload-artifact@v1`
  - `shithub/download-artifact@v1`
 -The runner does not execute them yet. A workflow containing those `uses:` steps
 -will fail until checkout and artifact execution land. If you need repository
 -files in a smoke workflow today, keep the command self-contained or fetch what
 -you need explicitly inside a `run:` step.
 +The runner does not execute artifact aliases yet. A workflow containing those
 +artifact `uses:` steps will fail until artifact execution lands. Checkout
 +inputs such as `path`, submodules, LFS, and persisted credentials are not
 +implemented yet.
  ## Expressions
  Most simple CI files need three edits:
 . Move the workflow file from `.github/workflows/` to `.shithub/workflows/`.
 -2. Replace `uses:` actions with equivalent `run:` commands.
 +2. Keep `actions/checkout@v4`, but replace marketplace and artifact `uses:`
 +   actions with equivalent `run:` commands for now.
 . Confirm `runs-on:` matches a label registered by your shithub operator.
  Marketplace actions, Docker actions, composite actions, hosted runner images,
 -matrix expansion, service containers, and built-in checkout are not part of the
 -current v1 runner.
 +matrix expansion, service containers, submodules, LFS, and artifact transfer
 +are not part of the current v1 runner.

tenseleyflow/shithub / `2a132b6`

8 changed files