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
++repository with a registered `ubuntu-latest` runner.
--`run:` steps because the current executor rejects reserved `uses:` aliases
++
--until checkout and artifact execution are implemented.
++`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
++API-purpose job JWTs are single-use. Every job endpoint verifies the
--expiry, checks that the path job belongs to the claimed runner/run, and
++signature and expiry, checks that the path job belongs to the claimed
--then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
++runner/run, and then inserts `jti` into `runner_jwt_used`. A replay
--support multi-step runner flows, successful in-flight job endpoints
++returns 401. To support multi-step runner flows, successful in-flight job
--return `next_token` and `next_token_expires_at`.
++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
++registration token, marks the job `running` with the first API-purpose job
--uses each returned `next_token` serially for log chunks, step-status
++JWT, then uses each returned `next_token` serially for log chunks,
--updates, cancel checks, artifact upload requests, and finally the
++step-status updates, cancel checks, artifact upload requests, and finally
--terminal job-status update. Reusing any consumed job JWT is a replay and
++the terminal job-status update. Reusing any consumed API-purpose job JWT
--must fail with 401.
++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
++The job payload includes `checkout_url`, `checkout_token`, resolved
--secrets shadow org secrets with the same name. The server also stores
++`secrets`, and `mask_values`; repo secrets shadow org secrets with the
--an encrypted claim-time copy of the mask values on
++same name. The server also stores an encrypted claim-time copy of the mask
--`workflow_job_secret_masks` so later log uploads are scrubbed against
++values on `workflow_job_secret_masks` so later log uploads are scrubbed
--the secrets that were actually handed to the runner, even if an
++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
++Runner execution supports host-side `actions/checkout@v4` followed by
--per-step log streaming and server-side log finalization. `uses:` aliases
++containerized `run:` steps with per-step log streaming and server-side log
--such as `actions/checkout@v4` and artifact upload/download remain
++finalization. Artifact upload/download aliases remain reserved until the
--reserved for the later S41d slices that add checkout metadata and
++artifact transfer path lands.
--artifact transfer.
  `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
++The current Docker executor runs `actions/checkout@v4` and `run:` steps.
--`uses:` alias deliberately instead of pretending checkout/artifact
++Checkout happens on the runner host before a containerized step mounts the
--semantics exist. This keeps the first end-to-end smoke path honest:
++workspace. The server issues a short-lived checkout-purpose JWT scoped to
--`run:`-only workflows are executable now, while repository checkout and
++the claimed repository and running job; the smart-HTTP handler accepts it
--artifact transfer remain explicit follow-up work.
++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
++now claims jobs, performs scoped `actions/checkout@v4`, and executes
--Podman. The curl flow below remains useful for token/replay debugging.
++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
++  Checkout and `run:` steps are executable; artifact aliases remain
--  the following S41d slices.
++  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
++The v1 executor supports host-side `actions/checkout@v4` plus containerized
--`actions/checkout@v4`, `shithub/upload-artifact@v1`, and
++`run:` steps. The checkout token is short-lived, repository-scoped, tied to a
--`shithub/download-artifact@v1`, but the Docker runner rejects `uses:` steps
++running job, and accepted only for read-only smart-HTTP fetches.
--until checkout metadata and artifact transfer are wired end to end. Do not use
++`shithub/upload-artifact@v1` and `shithub/download-artifact@v1` are still
--`actions/checkout@v4` in production smoke workflows yet.
++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
++- **`actions/checkout@v4` fails:** confirm the job is still running, the repo
--  checkout/artifact support lands.
++  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
++The runner does not execute artifact aliases yet. A workflow containing those
--will fail until checkout and artifact execution land. If you need repository
++artifact `uses:` steps will fail until artifact execution lands. Checkout
--files in a smoke workflow today, keep the command self-contained or fetch what
++inputs such as `path`, submodules, LFS, and persisted credentials are not
--you need explicitly inside a `run:` step.
++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
++matrix expansion, service containers, submodules, LFS, and artifact transfer
--current v1 runner.
++are not part of the current v1 runner.

tenseleyflow/shithub / `2a132b6`

8 changed files