`1baf580`

actions: document arbitrary repo smoke

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 17 hours ago

SHA: 1baf5803a9a155cdfaaf91022b3c5fc9f1910519
Parents: b9f1094
Tree: 21a4e6d

5 changed files

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

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'

  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