Skip to content

feat(webhook): A job may carry a job label that pins its runner to it - #57

Merged
sodre merged 4 commits into
mainfrom
t3/implement-55
Nov 21, 2026
Merged

sodre merged 4 commits into
mainfrom
t3/implement-55

Conversation

@sodre

@sodre sodre commented Nov 21, 2026

Copy link
Copy Markdown
Member

Closes #55

Summary

A job can now carry a job label, ci-job-<run_id>-<run_attempt>-<job key>-<matrix index>, and the runner launched for it registers with that label, so no other labelled job can take that runner. A job without the label is served exactly as before. The label is optional for now; #56 Require the job label, and remove the swap repair makes it required.

webhook, on workflow_job queued
  fence 3, then the label contract (shapeOf), as before   -> ignored: labels
  jobLabelFault(labels, workflow_job)                      -> ignored: job label, logged with a `why`
    none                         -> served as before
    two ci-job- labels           -> "two job labels"
    not ci-job-<n>-<n>-...       -> "job label without its run and attempt"
    another run_id / run_attempt -> "job label of another run" / "... another attempt"
    nothing after the attempt    -> "job label names no job"
    over 255 characters          -> "job label over 255 characters"
  enqueue, labels unchanged -> launcher mints the JIT config with them (unchanged)

What a reader should know:

  • The ticket's workflow form doesn't work as written. Inside runs-on, github.job evaluates to an empty string, so ci-job-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}-${{ strategy.job-index }} gives every job in a run with no matrix the same label. The docs therefore tell consumers to type the job key by hand. The webhook check is unaffected: it reads only the run and the attempt. This is a choice the ticket left open (it asked what github.job evaluates to).
  • Swaps don't end until the label is required. GitHub gives a job to a runner whose labels include all of the job's. So a runner with a job label can still take a job of its shape that has none. ADR 0004 and the docs say so, and the swap repair still covers that case until Require the job label, and remove the swap repair #56.
  • Two checks the ticket didn't list, added after review: a malformed label gets its own reason (it was logged as another run's), and a label over 255 characters is ignored, since GitHub can't put it on a runner (see below). The label is checked after the shape, so a job that isn't ours logs nothing, whatever ci-job- label it carries.

The three questions, answered

Each was measured on 2026-11-20 in the private scratch repo zeroae/foresight-migration-scratch. A probe workflow's runs-on held only labels no runner has. I read the queued jobs' evaluated labels back with GET /repos/.../actions/runs/<id>/jobs, then cancelled the runs and deleted the probe branch.

  1. strategy.job-index in a job with no matrix evaluates to 0 inside runs-on. A two-entry matrix gave 0 and 1. The docs use it in every form.

  2. github.job evaluates to an empty string inside runs-on, in a plain job and in a reusable workflow's job alike. Both gave ci-job-<run>-1--0. Two calls of one reusable workflow got the same label, ci-job-<run>-1--0, unless an input differed: call: a gave ...-0-a. So the docs tell consumers:

    • type the job key by hand;
    • give a reusable workflow an input the caller makes unique, and put it in the label;
    • when the caller has a matrix, pass ${{ strategy.job-index }} in that input too (probed: call-mat-0, call-mat-1).

    All three documented forms were checked the same way: an array runs-on with an expression item, cond && fromJSON(format('[...]', ...)) || 'ubuntu-latest', and the reusable workflow with an input.

  3. GitHub's runner label limit is 255 characters. I called POST /repos/.../actions/runners/generate-jitconfig with labels of 100, 200 and 255 characters: all were stored whole. A 256-character label was accepted but stored cut to 255. Labels of 257 and 300 were refused: Labels must be less than 256 characters in length. Every probe runner was deleted after. A 98-character job key is accepted, and a 100-character one is a workflow file error. So the longest likely label is under 130 characters (11-digit run id, 2-digit attempt, 98-character key, 3-digit index) plus a reusable workflow's input.

Evidence

Criterion Ticked Shown by
A queued job with the job label of its own run and attempt is enqueued with the label in labels yes a queued job with the job label of its own run and attempt is enqueued with the label
A ci-job- label naming another run, or another attempt, is ignored with a log line naming the reason yes a job whose job label names another run / names another attempt is ignored, and the log says why
Two ci-job- labels, or ci-job-<run_id>-<run_attempt>- with nothing after it, is ignored yes a job with two job labels is ignored…; a job label with nothing after its run and attempt is ignored…
A job without the label is handled exactly as before; the existing tests pass unchanged yes node --test test/*.test.js (no existing test body changed; the shared payload helper gained run_attempt: 2, a field GitHub always sends)
The launcher registers the runner for a labelled job with the job label among its labels yes the runner for a job with a job label registers with that label
ADR 0004 supersedes ADR 0003; the stack docs, traps and glossary describe the label and how to write it yes Spec review, round 1, read docs/adr/0004-…, ADR 0003's added line, docs/stack.md "The job label", docs/traps.md and GLOSSARY.md and found them complete; the written forms were run in the scratch-repo probe above
The three "to find out" questions are answered in the PR, each with how it was found yes the scratch-repo probe runs and generate-jitconfig calls under "The three questions, answered"
The existing test suite passes yes node --test test/*.test.js
Test Red Green
a queued job with the job label of its own run and attempt is enqueued with the label before the change: 200 !== 202 ok
a job whose job label names another run / another attempt is ignored, and the log says why before jobLabelFault: both failed (no log line) ok
a job with two job labels is ignored, and the log says why before the two-label check: enqueued ok
a job label with nothing after its run and attempt is ignored, and the log says why before the empty-rest check: enqueued ok
the job label is read case-insensitively passed at once; with toLowerCase() removed before the match: failed ok
a job whose job label leaves out the attempt / stops at the attempt is ignored, and the log says why before the fix: logged job label of another run ok
a job whose job label is 256 characters long is ignored, and the log says why before the fix: enqueued ok
a job label just under GitHub's 255-character limit is accepted passed at once; with the limit set to 254: failed ok
a job outside the label contract is ignored without a log line, whatever its job label before the reorder: logged a job-label line ok
the runner for a job with a job label registers with that label (launcher) passed at once on the unchanged launcher; with ci-job- labels filtered out of the JIT mint: failed ok

node --test test/*.test.js on dc848c9: 205 tests, 205 passed, 0 skipped, 0 failed. make build: build/template.yaml 80,332 of 1,048,576 bytes.

Not run: a live run on the stack (docs/runbook.md "Proving a change live"). The webhook change is covered with fakes. No consumer carries the label yet, so a live run would need a hand-made workflow; it is first exercised when a consumer adopts the label.

Merge Danger

Door: two-way. A revert drops the job label from the contract: a job carrying one is then ignored as outside it (ignored: labels) until its workflow drops the label.

Blast Radius: queued jobs that carry a ci-job- label (none today).

The merge changes the webhook Lambda only, inlined into the template, and deploys with make deploy. No image, no new infrastructure, no IAM change, no flag. Jobs without the label behave as before.

Reviews

Correctness, Standards, Spec and Security, two rounds: 12 findings, each with its outcome

Correctness, round 1 (c55cf70, medium)

  1. Swap repair rebuilds a re-queued job's labels from the ci-runner:labels tag, which is cut to 256 characters (and sanitized on ECS), so a long job label could come back damaged. Pushed back: it needs a job label of about 215 characters or more, against a likely maximum under 130; and Require the job label, and remove the swap repair #56 Require the job label, and remove the swap repair deletes this code.
  2. A malformed job label (ci-job-444-tests-0) was logged as job label of another run. Fixed: its own reason, job label without its run and attempt.
  3. A job label of 256 characters or more was enqueued, though GitHub refuses it or cuts it as a runner label. Fixed: ignored as job label over 255 characters.
  4. A job that isn't ours but carries a bad ci-job- label was logged. Fixed: the job label is checked after the shape.
  5. A payload with no run_attempt rejects every labelled job. Pushed back: github.com's workflow_job payload always carries run_attempt, and without it only labelled jobs are refused, with the reason logged.
  6. The ci-job- prefix test was written twice. Fixed: one isJobLabel helper.
  7. No test covered a malformed job label. Fixed: two table rows.

Standards, round 1

  1. A magic why.slice(13) in a test title. Fixed: the table carries the title's phrase.
  2. The prefix test duplicated (as 6). Fixed: one isJobLabel helper.
  3. A malformed label's why (as 2). Fixed: its own reason.
  4. The Swap repair and glossary wording overstate what the label prevents. Pushed back: "unless X carries a job label" is about the job taken, which is what decides a swap, and a labelled Y's runner taking an unlabelled X is covered by it.

Spec, round 1: no findings.

Security, round 1 (run because this repo has no security-path list): no findings.

Correctness, round 2 (dc848c9, low): no findings. Standards, round 2: no findings.

Spec, round 2

  1. The 255-character check is behaviour the ticket didn't list. Pushed back: GitHub can't put such a label on a runner (measured), so serving the job only launches a runner that can never take it, about once an hour; ignoring it with a logged reason is what the ticket does for every other job label a runner can't carry.

Security, round 2: no findings.

Tracking

Epic: none
Spec: none
Ticket: #55 A job label pins each runner to the job it was launched for
Flag: none

🤖 Generated with Claude Code

sodre and others added 4 commits November 20, 2026 20:18
…mpt>-<rest>

A job label of another run or attempt, two job labels, or one naming no
job is ignored, and the log line says why. A job without it is served as
before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…label

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
How to write the label in runs-on (the job key by hand, since github.job
is empty there), in a reusable workflow, and GitHub's label length limit,
each measured in a scratch repo on 2026-11-20.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cked after the shape

A job label without its run and attempt was logged as another run's; one
over 255 characters, which GitHub refuses or cuts as a runner label, was
enqueued. A job outside the label contract is now ignored silently
whatever job label it carries. One isJobLabel test serves both checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sodre
sodre marked this pull request as ready for review November 21, 2026 01:36
@sodre
sodre merged commit 799873d into main Nov 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A job label pins each runner to the job it was launched for

1 participant