Skip to content

docs: the queue classifier has ten causes, three of which add a runner #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
addisdev merged 1 commit into from
Oct 27, 2026
Merged

docs: the queue classifier has ten causes, three of which add a runner #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,9 +186,10 @@ The other question the fleet has to answer is why a job is sitting in a queue.
That used to be one check — *is a runner idle* — which separated the wrong pair,
because "every runner is busy" and "the host is saturated" both look like *no
runner is idle*, and only the first is fixed by adding a runner. It is now
[eight classified causes](https://addisdev.github.io/actions-runners/concepts/#why-a-job-is-queued),
each carrying the evidence it used, and exactly one of them offers to add a
runner.
[ten classified causes](https://addisdev.github.io/actions-runners/concepts/#why-a-job-is-queued),
each carrying the evidence it used, and only three of them — no runner for the
repo, none for the job's role, or every runner busy with headroom to spare — are
fixed by adding one.

## The numbers exclude what would make them wrong

Expand Down
8 changes: 4 additions & 4 deletions dashboard/lib/queue-cause.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
// WHY A CLASSIFIER OVER A BOOLEAN FLAG
//
// The existing `stuck-queue` drift rule forks on a single question: is there an
// idle runner or not? That answers two of seven causes. The others are invisible
// idle runner or not? That answers two of ten causes. The others are invisible
// — a label mismatch looks like a capacity problem when you can see only that
// "all runners are busy", and host saturation looks like a capacity problem when
// the headroom gate is refusing additions. Misreading the cause leads to the
Expand Down Expand Up @@ -125,9 +125,9 @@ export function classifyQueueCause({ run, runners, capacity, api = {}, collector
// ---- no runners at all -------------------------------------------------
if (repoRunners.length === 0) {
evidence.push('No runner is registered for this repo');
// Action-eligible, unlike every other non-capacity cause here. The field
// means "adding a runner would help", and for the six causes marked false it
// genuinely would not — a second runner shares a label mismatch, and another
// Action-eligible, like role-unserved and repo-capacity and unlike the
// rest. The field means "adding a runner would help", and for the seven
// causes marked false it genuinely would not — a second runner shares a label mismatch, and another
// runner on a saturated host makes the saturation worse. A repo with no
// runner is the opposite case: one runner is the entire remedy, and
// RECOMMENDED has said so all along.
Expand Down
Loading