shithub Public

Watch 1 Fork 0 Star 0

markdown · 3249 bytes Raw Blame History

Actions runner API

The runner-facing HTTP surface lives in internal/web/handlers/api/runners.go. It is mounted under /api/v1 in the CSRF-exempt API group, but it does not use PAT auth. Runners authenticate first with a long-lived registration token and then with short-lived per-job JWTs.

Auth model

Operators register a runner with:

shithubd admin runner register --name runner-1 --labels self-hosted,linux,ubuntu-latest

The command inserts workflow_runners, stores only a SHA-256 hash in runner_tokens, and prints the 32-byte hex token once.

POST /api/v1/runners/heartbeat accepts:

Authorization: Bearer <registration-token>

When a queued job matches the runner labels and capacity is available, the response includes a job payload and a 15-minute job JWT. That JWT has claims:

{"sub":"runner:<id>","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 non-terminal job endpoints return next_token and next_token_expires_at.

Endpoints

POST /api/v1/runners/heartbeat

Request body:

{"labels":["ubuntu-latest","linux"],"capacity":1}

Returns 204 when no matching job is claimable. Returns 200 with 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.

POST /api/v1/jobs/{id}/logs

Auth: job JWT. Body:

{"seq":0,"chunk":"aGVsbG8K","step_id":123}

step_id is optional for the S41c curl smoke path; when omitted the first step in the job receives the chunk. Chunks are base64-decoded, capped at 512 KiB raw, and appended to workflow_step_log_chunks. Duplicate (step_id, seq) inserts are accepted as idempotent retries.

POST /api/v1/jobs/{id}/status

Auth: job JWT. Body:

{"status":"completed","conclusion":"success"}

Valid transitions are queued|running -> running|completed|cancelled. Completed jobs require a valid check conclusion. The handler updates workflow_jobs, rolls up workflow_runs, and best-effort updates the matching check_runs row created by the trigger pipeline.

POST /api/v1/jobs/{id}/artifacts/upload

Auth: job JWT. Body:

{"name":"test-results.tgz","size_bytes":12345}

Creates a workflow_artifacts row and returns a pre-signed S3 PUT URL. The object key is actions/runs/<run_id>/artifacts/<name>.

POST /api/v1/jobs/{id}/cancel-check

Auth: job JWT. Returns:

{"cancelled":false,"next_token":"..."}

The boolean mirrors workflow_jobs.cancel_requested; the actual cancel request UI lands later in S41g.

Metrics

shithub_actions_runner_registrations_total
shithub_actions_runner_heartbeats_total{result="claimed|no_job"}
shithub_actions_runner_jwt_total{result="issued|rejected|replay"}

View source

  
        1
        # Actions runner API
      
        2
        
        3
        The runner-facing HTTP surface lives in
      
        4
        `internal/web/handlers/api/runners.go`. It is mounted under `/api/v1`
      
        5
        in the CSRF-exempt API group, but it does not use PAT auth. Runners
      
        6
        authenticate first with a long-lived registration token and then with
      
        7
        short-lived per-job JWTs.
      
        8
        
        9
        ## Auth model
      
        10
        
        11
        Operators register a runner with:
      
        12
        
        13
        ```sh
      
        14
        shithubd admin runner register --name runner-1 --labels self-hosted,linux,ubuntu-latest
      
        15
        ```
      
        16
        
        17
        The command inserts `workflow_runners`, stores only a SHA-256 hash in
      
        18
        `runner_tokens`, and prints the 32-byte hex token once.
      
        19
        
        20
        `POST /api/v1/runners/heartbeat` accepts:
      
        21
        
        22
        ```http
      
        23
        Authorization: Bearer <registration-token>
      
        24
        ```
      
        25
        
        26
        When a queued job matches the runner labels and capacity is available,
      
        27
        the response includes a job payload and a 15-minute job JWT. That JWT
      
        28
        has claims:
      
        29
        
        30
        ```json
      
        31
        {"sub":"runner:<id>","job_id":1,"run_id":1,"repo_id":1,"exp":0,"jti":"..."}
      
        32
        ```
      
        33
        
        34
        The signing key is derived from `auth.totp_key_b64` with HKDF label
      
        35
        `actions-runner-jwt-v1`; the raw TOTP/secretbox key is not used
      
        36
        directly for JWT signing.
      
        37
        
        38
        Job JWTs are single-use. Every job endpoint verifies the signature and
      
        39
        expiry, checks that the path job belongs to the claimed runner/run, and
      
        40
        then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
      
        41
        support multi-step runner flows, successful non-terminal job endpoints
      
        42
        return `next_token` and `next_token_expires_at`.
      
        43
        
        44
        ## Endpoints
      
        45
        
        46
        `POST /api/v1/runners/heartbeat`
      
        47
        
        48
        Request body:
      
        49
        
        50
        ```json
      
        51
        {"labels":["ubuntu-latest","linux"],"capacity":1}
      
        52
        ```
      
        53
        
        54
        Returns 204 when no matching job is claimable. Returns 200 with
      
        55
        `token`, `expires_at`, and `job` when a job is claimed. Capacity is
      
        56
        enforced server-side by counting current `workflow_jobs.status =
      
        57
        'running'` rows for the runner while holding a row lock on the runner.
      
        58
        
        59
        `POST /api/v1/jobs/{id}/logs`
      
        60
        
        61
        Auth: job JWT. Body:
      
        62
        
        63
        ```json
      
        64
        {"seq":0,"chunk":"aGVsbG8K","step_id":123}
      
        65
        ```
      
        66
        
        67
        `step_id` is optional for the S41c curl smoke path; when omitted the
      
        68
        first step in the job receives the chunk. Chunks are base64-decoded,
      
        69
        capped at 512 KiB raw, and appended to `workflow_step_log_chunks`.
      
        70
        Duplicate `(step_id, seq)` inserts are accepted as idempotent retries.
      
        71
        
        72
        `POST /api/v1/jobs/{id}/status`
      
        73
        
        74
        Auth: job JWT. Body:
      
        75
        
        76
        ```json
      
        77
        {"status":"completed","conclusion":"success"}
      
        78
        ```
      
        79
        
        80
        Valid transitions are `queued|running -> running|completed|cancelled`.
      
        81
        Completed jobs require a valid check conclusion. The handler updates
      
        82
        `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
      
        83
        matching `check_runs` row created by the trigger pipeline.
      
        84
        
        85
        `POST /api/v1/jobs/{id}/artifacts/upload`
      
        86
        
        87
        Auth: job JWT. Body:
      
        88
        
        89
        ```json
      
        90
        {"name":"test-results.tgz","size_bytes":12345}
      
        91
        ```
      
        92
        
        93
        Creates a `workflow_artifacts` row and returns a pre-signed S3 PUT URL.
      
        94
        The object key is `actions/runs/<run_id>/artifacts/<name>`.
      
        95
        
        96
        `POST /api/v1/jobs/{id}/cancel-check`
      
        97
        
        98
        Auth: job JWT. Returns:
      
        99
        
        100
        ```json
      
        101
        {"cancelled":false,"next_token":"..."}
      
        102
        ```
      
        103
        
        104
        The boolean mirrors `workflow_jobs.cancel_requested`; the actual cancel
      
        105
        request UI lands later in S41g.
      
        106
        
        107
        ## Metrics
      
        108
        
        109
        - `shithub_actions_runner_registrations_total`
      
        110
        - `shithub_actions_runner_heartbeats_total{result="claimed|no_job"}`
      
        111
        - `shithub_actions_runner_jwt_total{result="issued|rejected|replay"}`

1	# Actions runner API
2
3	The runner-facing HTTP surface lives in
4	`internal/web/handlers/api/runners.go`. It is mounted under `/api/v1`
5	in the CSRF-exempt API group, but it does not use PAT auth. Runners
6	authenticate first with a long-lived registration token and then with
7	short-lived per-job JWTs.
8
9	## Auth model
10
11	Operators register a runner with:
12
13	```sh
14	shithubd admin runner register --name runner-1 --labels self-hosted,linux,ubuntu-latest
15	```
16
17	The command inserts `workflow_runners`, stores only a SHA-256 hash in
18	`runner_tokens`, and prints the 32-byte hex token once.
19
20	`POST /api/v1/runners/heartbeat` accepts:
21
22	```http
23	Authorization: Bearer <registration-token>
24	```
25
26	When a queued job matches the runner labels and capacity is available,
27	the response includes a job payload and a 15-minute job JWT. That JWT
28	has claims:
29
30	```json
31	{"sub":"runner:<id>","job_id":1,"run_id":1,"repo_id":1,"exp":0,"jti":"..."}
32	```
33
34	The signing key is derived from `auth.totp_key_b64` with HKDF label
35	`actions-runner-jwt-v1`; the raw TOTP/secretbox key is not used
36	directly for JWT signing.
37
38	Job JWTs are single-use. Every job endpoint verifies the signature and
39	expiry, checks that the path job belongs to the claimed runner/run, and
40	then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
41	support multi-step runner flows, successful non-terminal job endpoints
42	return `next_token` and `next_token_expires_at`.
43
44	## Endpoints
45
46	`POST /api/v1/runners/heartbeat`
47
48	Request body:
49
50	```json
51	{"labels":["ubuntu-latest","linux"],"capacity":1}
52	```
53
54	Returns 204 when no matching job is claimable. Returns 200 with
55	`token`, `expires_at`, and `job` when a job is claimed. Capacity is
56	enforced server-side by counting current `workflow_jobs.status =
57	'running'` rows for the runner while holding a row lock on the runner.
58
59	`POST /api/v1/jobs/{id}/logs`
60
61	Auth: job JWT. Body:
62
63	```json
64	{"seq":0,"chunk":"aGVsbG8K","step_id":123}
65	```
66
67	`step_id` is optional for the S41c curl smoke path; when omitted the
68	first step in the job receives the chunk. Chunks are base64-decoded,
69	capped at 512 KiB raw, and appended to `workflow_step_log_chunks`.
70	Duplicate `(step_id, seq)` inserts are accepted as idempotent retries.
71
72	`POST /api/v1/jobs/{id}/status`
73
74	Auth: job JWT. Body:
75
76	```json
77	{"status":"completed","conclusion":"success"}
78	```
79
80	Valid transitions are `queued\|running -> running\|completed\|cancelled`.
81	Completed jobs require a valid check conclusion. The handler updates
82	`workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
83	matching `check_runs` row created by the trigger pipeline.
84
85	`POST /api/v1/jobs/{id}/artifacts/upload`
86
87	Auth: job JWT. Body:
88
89	```json
90	{"name":"test-results.tgz","size_bytes":12345}
91	```
92
93	Creates a `workflow_artifacts` row and returns a pre-signed S3 PUT URL.
94	The object key is `actions/runs/<run_id>/artifacts/<name>`.
95
96	`POST /api/v1/jobs/{id}/cancel-check`
97
98	Auth: job JWT. Returns:
99
100	```json
101	{"cancelled":false,"next_token":"..."}
102	```
103
104	The boolean mirrors `workflow_jobs.cancel_requested`; the actual cancel
105	request UI lands later in S41g.
106
107	## Metrics
108
109	- `shithub_actions_runner_registrations_total`
110	- `shithub_actions_runner_heartbeats_total{result="claimed\|no_job"}`
111	- `shithub_actions_runner_jwt_total{result="issued\|rejected\|replay"}`