actions: document arbitrary repo smoke

Status	File	+	-
M	`docs/internal/runbooks/actions-runner.md`	92	1
M	`docs/internal/runbooks/runner-deploy.md`	7	0
M	`docs/public/user/actions.md`	25	0
M	`internal/actions/workflow/parse_test.go`	36	0
A	`tests/fixtures/workflows/arbitrary-repo-smoke.yml`	13	0

docs/internal/runbooks/actions-runner.mdmodified

  Prereqs:
--- Database migrations are current through `0057_workflow_job_secret_masks.sql`.
++- Database migrations are current through `0067_runner_pool_ops.sql`.
  - `SHITHUB_TOTP_KEY` or `auth.totp_key_b64` is set on the web process.
  - Object storage is configured if testing artifact upload.
  - Docker or Podman is installed on the runner host.
  Use `--expires-in` only for tokens that your automation rotates before expiry;
  the runner presents its registration token on every heartbeat.
++## Arbitrary Repository Smoke
++
++Use this checklist after provisioning a shared runner pool or changing runner
++labels. The purpose is to prove that ordinary repositories can use the pool
++without repo-specific labels.
++
++Pick at least two repositories:
++
++- `mfwolffe/scratch`, the historical dogfood repo;
++- one additional public repository;
++- one private repository if one is available for the operator account.
++
++In each repository, commit this file as `.shithub/workflows/smoke.yml` on
++`trunk`:
++
++```yaml
++name: Smoke
++on:
++  push:
++    branches: [trunk]
++jobs:
++  green:
++    runs-on: ubuntu-latest
++    steps:
++      - uses: actions/checkout@v4
++      - name: Verify checkout
++        run: test -f README.md || test -f readme.md || pwd
++      - name: Smoke
++        run: printf 'shithub actions smoke passed\n'
++```
++
++Expected results for each repo:
++
++- the repo heading shows a green check after the push;
++- the Actions run page shows `Triggered via push` on `refs/heads/trunk`;
++- the `green` job is completed with conclusion `success`;
++- the checkout step logs the scoped repository URL for that repo;
++- the smoke step log contains `shithub actions smoke passed`;
++- the check run attached to the commit agrees with the workflow run state;
++- the downloaded or raw archived step log matches the in-page step log.
++
++Confirm the pool is shared:
++
++```sh
++shithubd admin runner list --output json
++shithubd admin runner queue --output json
++```
++
++The same online runner labels should satisfy both repositories. The smoke
++workflow must use `runs-on: ubuntu-latest`; do not add per-repo labels for this
++test.
++
++Unsupported-label negative test:
++
++```yaml
++name: Unsupported runner label
++on:
++  workflow_dispatch:
++jobs:
++  nope:
++    runs-on: windows-latest
++    steps:
++      - run: echo should-not-run
++```
++
++Trigger it manually. The run should stay queued and the run page should say
++`Waiting for runner with labels: windows-latest`. `shithubd admin runner queue
++--output json` should show one queued `windows-latest` job with zero matching
++runners. Cancel the run after confirming the diagnostic.
++
++Untrusted-PR secret negative test:
++
++1. Add a repo secret named `S41J_SECRET_SMOKE` with any non-production value.
++2. Open an untrusted pull request whose workflow prints whether that secret is
++   present.
++3. Before approval, confirm the claimed job contains no injected secrets and
++   logs do not contain the secret value.
++4. Only after explicit approval should the run be allowed through the trusted
++   secret path.
++
++Runner-outage negative test:
++
++1. Drain every shared runner with `shithubd admin runner drain --id <id>`.
++2. Push the smoke workflow to a test repo.
++3. Confirm the run stays queued with the requested `ubuntu-latest` label visible.
++4. Undrain one runner and confirm the same queued job is claimed and completes.
++
++This smoke is considered passing only when scratch and the second repository
++both complete from the same shared label set and the negative cases produce
++clear queued/secret-denied behavior.
++
  The Ansible runner role creates the `shithub-actions` bridge, runs the
  allowlist resolver at `172.30.0.1`, and installs firewall rules that
  reject direct-IP egress from step containers. If you run the binary

docs/internal/runbooks/runner-deploy.mdmodified

  Repeat with `exit 1`; the check should complete with conclusion
  `failure`.
++Before declaring a shared pool available to arbitrary repositories, run the
++[arbitrary repository smoke](./actions-runner.md#arbitrary-repository-smoke)
++checklist against scratch and at least one additional repository. The single
++repo check above proves the runner process works; the arbitrary-repo smoke
++proves label routing, checkout scoping, archived logs, check runs, and negative
++queue/secret cases across normal repositories.
++
  Sandbox smoke checks:
  ```yaml

docs/public/user/actions.mdmodified

  The run appears under the repository's Actions tab and its job also appears as
  a check run on matching pull requests.
++## Copy-paste smoke workflow
++
++Use this workflow to confirm a normal repository can use the shared Linux pool.
++It runs on every push to `trunk` while Actions are enabled for the repository
++and a runner advertising `ubuntu-latest` is online.
++
++```yaml
++name: Smoke
++on:
++  push:
++    branches: [trunk]
++jobs:
++  green:
++    runs-on: ubuntu-latest
++    steps:
++      - uses: actions/checkout@v4
++      - name: Verify checkout
++        run: test -f README.md || test -f readme.md || pwd
++      - name: Smoke
++        run: printf 'shithub actions smoke passed\n'
++```
++
++The same file should work in any repository that is allowed by the site, org,
++and repo Actions policies. It should not need a repo-specific runner label.
++
  ## What works today
  - `push`, `pull_request`, `schedule`, and `workflow_dispatch` triggers

internal/actions/workflow/parse_test.gomodified

+ 	}
+ }
++func TestParse_ArbitraryRepoSmoke(t *testing.T) {
++	t.Parallel()
++	w, diags, err := workflow.Parse(readFixture(t, "arbitrary-repo-smoke"))
++	if err != nil {
++		t.Fatalf("Parse: %v", err)
++	}
++	if len(diags) != 0 {
++		t.Fatalf("unexpected diagnostics: %v", diags)
++	}
++	if w.Name != "Smoke" {
++		t.Fatalf("Name = %q, want Smoke", w.Name)
++	}
++	if w.On.Push == nil || len(w.On.Push.Branches) != 1 || w.On.Push.Branches[0] != "trunk" {
++		t.Fatalf("push branches = %+v", w.On.Push)
++	}
++	if len(w.Jobs) != 1 {
++		t.Fatalf("len(Jobs) = %d", len(w.Jobs))
++	}
++	job := w.Jobs[0]
++	if job.Key != "green" || job.RunsOn != "ubuntu-latest" {
++		t.Fatalf("job = %+v", job)
++	}
++	if len(job.Steps) != 3 {
++		t.Fatalf("steps = %+v", job.Steps)
++	}
++	if job.Steps[0].Uses != "actions/checkout@v4" {
++		t.Fatalf("checkout step = %+v", job.Steps[0])
++	}
++	if job.Steps[1].Name != "Verify checkout" || !strings.Contains(job.Steps[1].Run, "README.md") {
++		t.Fatalf("verify step = %+v", job.Steps[1])
++	}
++	if job.Steps[2].Name != "Smoke" || !strings.Contains(job.Steps[2].Run, "shithub actions smoke passed") {
++		t.Fatalf("smoke step = %+v", job.Steps[2])
++	}
++}
++
  func TestParse_MultiJob(t *testing.T) {
  	t.Parallel()
  	w, diags, err := workflow.Parse(readFixture(t, "multi-job"))

tests/fixtures/workflows/arbitrary-repo-smoke.ymladded

++name: Smoke
++on:
++  push:
++    branches: [trunk]
++jobs:
++  green:
++    runs-on: ubuntu-latest
++    steps:
++      - uses: actions/checkout@v4
++      - name: Verify checkout
++        run: test -f README.md || test -f readme.md || pwd
++      - name: Smoke
++        run: printf 'shithub actions smoke passed\n'

tenseleyflow/shithub / `1baf580`

5 changed files