tenseleyflow/shithub / 3fea666

Browse files

runner: build runner binary and document PR1

Authored by mfwolffe <wolffemf@dukes.jmu.edu>
SHA
3fea6668a9eaa08fda60d1def6f7e4aa554c7600
Parents
732831b
Tree
a9a8d2a

5 changed files

StatusFile+-
M .github/workflows/ci.yml 1 1
M Makefile 4 2
M docs/internal/actions-runner-api.md 10 0
M docs/internal/actions-schema.md 3 2
M docs/internal/runbooks/actions-runner.md 44 2
.github/workflows/ci.ymlmodified
@@ -49,4 +49,4 @@ jobs:
4949
         run: go test -trimpath ./...
5050
5151
       - name: Build
52
-        run: go build -trimpath ./cmd/shithubd
52
+        run: make build
Makefilemodified
@@ -14,6 +14,7 @@ LDFLAGS := -X github.com/tenseleyFlow/shithub/internal/version.Version=$(VERSION
1414
1515
 GOFLAGS := -trimpath
1616
 BIN     := bin/shithubd
17
+RUNNER_BIN := bin/shithubd-runner
1718
1819
 # Tools installed via 'go install' live in GOBIN (or GOPATH/bin). Reference
1920
 # them by absolute path so make recipes don't depend on PATH ordering.
@@ -39,9 +40,10 @@ dev-run: ## Run the binary directly (no air); sources .env.
3940
 	@if [ -f .env ]; then set -a; . ./.env; set +a; fi; \
4041
 	go run ./cmd/shithubd web
4142
42
-build: ## Build the shithubd binary into bin/.
43
-	@mkdir -p bin
43
+build: ## Build shithubd and shithubd-runner into bin/.
44
+	@mkdir -p $(dir $(BIN)) $(dir $(RUNNER_BIN))
4445
 	go build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BIN) ./cmd/shithubd
46
+	go build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(RUNNER_BIN) ./cmd/shithubd-runner
4547
4648
 test: ## Run unit tests.
4749
 	go test $(GOFLAGS) ./...
docs/internal/actions-runner-api.mdmodified
@@ -41,6 +41,11 @@ then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
4141
 support multi-step runner flows, successful non-terminal job endpoints
4242
 return `next_token` and `next_token_expires_at`.
4343
44
+`shithubd-runner` consumes the same token chain: it claims with the
45
+registration token, marks the job `running` with the first job JWT, then
46
+uses the returned `next_token` for the terminal status update. Reusing
47
+any consumed job JWT is a replay and must fail with 401.
48
+
4449
 ## Endpoints
4550
4651
 `POST /api/v1/runners/heartbeat`
@@ -82,6 +87,11 @@ Completed jobs require a valid check conclusion. The handler updates
8287
 `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
8388
 matching `check_runs` row created by the trigger pipeline.
8489
90
+S41d PR1 runner execution supports containerized `run:` steps. `uses:`
91
+aliases such as `actions/checkout@v4` and artifact upload/download are
92
+reserved for the later S41d slices that add checkout metadata, log
93
+streaming, and artifact transfer.
94
+
8595
 `POST /api/v1/jobs/{id}/artifacts/upload`
8696
8797
 Auth: job JWT. Body:
docs/internal/actions-schema.mdmodified
@@ -438,7 +438,8 @@ defer to S41g where the lifecycle work touches that surface anyway.
438438
439439
 ### What S41b deliberately doesn't do
440440
441
-- Run jobs. Runs sit in `queued` forever — S41c+ runner work.
441
+- Run jobs. S41c adds runner claim/status APIs; S41d adds the actual
442
+  `shithubd-runner` execution binary.
442443
 - Schedule sweep. Cron-driven triggers split into S41b-2 to keep
443444
   this PR reviewable; the trigger pipeline accepts schedule events,
444445
   but no caller produces them yet. S41b-2 adds the sweep + the
@@ -487,7 +488,7 @@ constraint.
487488
488489
 - No trigger pipeline. `domain_events` aren't matched against `on:`
489490
   yet — that's S41b.
490
-- No runner. Jobs land in `queued` and stay there — S41c onward.
491
+- No runner. S41c/S41d add runner claim APIs and the execution binary.
491492
 - No UI. The Actions tab still renders the placeholder — S41f.
492493
 - No secret encryption helpers wired to anything writable — S41c.
493494
 - No JWT issuance, no runner registration flow — S41c.
docs/internal/runbooks/actions-runner.mdmodified
@@ -1,15 +1,19 @@
11
 # Actions runner smoke runbook
22
3
-This runbook drives one queued Actions job with curl. It is for S41c
4
-operator validation before the real `shithubd-runner` binary lands.
3
+This runbook validates the runner-facing Actions path. `shithubd-runner`
4
+now claims jobs and executes containerized `run:` steps through Docker or
5
+Podman. The curl flow below remains useful for token/replay debugging.
56
67
 Prereqs:
78
89
 - Database migrations are current through `0053_runner_jwt_used.sql`.
910
 - `SHITHUB_TOTP_KEY` or `auth.totp_key_b64` is set on the web process.
1011
 - Object storage is configured if testing artifact upload.
12
+- Docker or Podman is installed on the runner host.
1113
 - A repo has a workflow under `.shithub/workflows/*.yml` with
1214
   `runs-on: ubuntu-latest`, and a push/dispatch has enqueued a run.
15
+  S41d PR1 supports `run:` steps; checkout and artifact aliases land in
16
+  the following S41d slices.
1317
1418
 Register a runner:
1519
@@ -27,6 +31,44 @@ export RUNNER_TOKEN='<printed-token>'
2731
 export BASE='https://shithub.example'
2832
 ```
2933
34
+Run the binary:
35
+
36
+```sh
37
+shithubd-runner run \
38
+  --server-url "$BASE" \
39
+  --token "$RUNNER_TOKEN" \
40
+  --labels self-hosted,linux,ubuntu-latest \
41
+  --workspace-root /var/lib/shithubd-runner/workspaces
42
+```
43
+
44
+Equivalent config file:
45
+
46
+```toml
47
+[server]
48
+base_url = "https://shithub.example"
49
+
50
+[runner]
51
+token = "<printed-token>"
52
+labels = ["self-hosted", "linux", "ubuntu-latest"]
53
+capacity = 1
54
+poll_interval = "5s"
55
+workspace_root = "/var/lib/shithubd-runner/workspaces"
56
+workspace_ttl = "24h"
57
+
58
+[engine]
59
+kind = "docker"
60
+default_image = "ghcr.io/shithub/runner-nix:1.0"
61
+network = "bridge"
62
+memory = "2g"
63
+cpus = "2"
64
+```
65
+
66
+The config path defaults to `/etc/shithubd-runner/config.toml`.
67
+Environment variables use the `SHITHUB_RUNNER_` prefix, for example
68
+`SHITHUB_RUNNER_TOKEN` or `SHITHUB_RUNNER_SERVER__BASE_URL`.
69
+
70
+## Curl token smoke
71
+
3072
 Claim a job:
3173
3274
 ```sh