route job at the start of the run asks Darkbloom which lanes it can take
and reserves capacity for their jobs. Each routed job then takes its runs-on
from the answer: Darkbloom’s runner labels, or the lane’s fallback label. If
Darkbloom is off, unreachable, slow or says no, every lane keeps its fallback,
so the run never depends on Darkbloom.
The route job runs on a GitHub-hosted ubuntu-24.04 runner, with no secrets
and with the token permissions its calling job grants. It sends Darkbloom the
repository name, the run ID and attempt, and each requested lane’s name, profile
and count.
Install the route workflow
- Copy
.github/workflows/route.ymlfrom a commit of the Darkbloom actions repository into your repository as.github/workflows/darkbloom-route.yml, unchanged. - Call it locally with
uses: ./.github/workflows/darkbloom-route.yml. Darkbloom checks each run’s workflow at its exact commit, and it cannot verify a reusable workflow from another repository: a workflow that calls one has every routed job refused. - Keep the route job’s
permissions: {}. The route workflow declares no permissions of its own, so its job holds exactly what the calling job grants: with{}, no token permission at all. - Set the repository variable
DARKBLOOM_ROUTINGto exactlyon. Any other value, or none, keeps every lane on its fallback without asking Darkbloom.
Declare lanes
One lane per line:<lane> <profile> <fallback-label> [count] [placement] [shape].
At most 32 lanes. A malformed line fails the
route job with a
Darkbloom route configuration error.
count must match the jobs the lane queues: Darkbloom reserves one slot per
job, and jobs beyond the count run on Darkbloom only if capacity is free when
they are queued.
Runner labels
A routed lane gets its profile’s labels, exactly:
For the lowest compute price, use
test linux_arm64 ubuntu-24.04-arm 2 cheapest. The requested profile label
then ends in -cheapest (for example, darkbloom-linux-arm64-cheapest); the
workflow accepts only those exact labels from Darkbloom. Omit placement to
preserve normal scheduling. Storage and network charges are unchanged.
For a lane needing more CPU, use
test linux_arm64 ubuntu-24.04-arm 1 balanced 8x32. Only that lane asks for
8 vCPUs and 32 GiB; omitted sizes keep the approved default. Its profile label
becomes darkbloom-linux-arm64-8x32, followed by -cheapest when requested and
the run qualifier when Darkbloom supplies it. An unavailable or unpriced size
keeps the lane’s fallback.
A caller workflow
Every job that may run on Darkbloom declares read-only token permissions, no secrets, and no environment, services or container:persist-credentials: false keeps the checkout token out of the workspace.
Jobs that publish, release or save caches that releases restore belong on your
own runners.
What routed jobs may do
Darkbloom admits a job only if its workflow passes these checks at the run’s commit; otherwise the job is refused and stays queued:- Explicit token permissions of
readornoneon the job or the workflow (read-alland missing permissions are refused). - No secrets: none in the job, the workflow’s
env, the local actions it uses or the local reusable workflows it calls (secrets: inheritincluded). Keep secrets in environments; a routed job cannot name one. - No
environment,services,containeror container actions. - No remote reusable workflows anywhere in the workflow.
- Only hosts Darkbloom approved for the repository are reachable over HTTPS (GitHub’s Actions hosts always are).
When a lane falls back
The route job writes each lane’s decision to its log and the run summary:
The per-reason answers are in troubleshooting.
Configuration
The watchdog workflow
A routed lane can no longer fall back once its jobs are queued: they can only run on a Darkbloom runner. Copywatchdog.yml as
.github/workflows/darkbloom-watchdog.yml beside the route workflow
(unchanged, like it). It rescues a run whose Darkbloom job has waited queued
with no runner too long, using only GitHub and the repository’s GITHUB_TOKEN,
so it works while Darkbloom is down or unreachable.
Every 10 minutes it lists the repository’s queued and in-progress runs of the
last day and their jobs. A run is stranded when its job carrying self-hosted
and a darkbloom-* label has been queued with no runner for
DARKBLOOM_WATCHDOG_MINUTES, timed from the job’s own creation, and no
Darkbloom job of the run was given a runner within that time. It cancels the
run and re-runs its route job and the jobs that need it (or the whole run when
it cannot tell which job is the route job), so the new attempt’s lanes fall
back. It rescues a run at most once.
A job that waits by design at your concurrency or resource limit looks the same
to it as a fault once no runner came for the whole wait. If your jobs can wait
that long at a limit, set DARKBLOOM_WATCHDOG_MINUTES above that wait.
Its token holds
actions: write and checks: write and nothing else. A
re-run repeats what the run’s jobs do: add the watchdog only to repositories
whose routed workflows are safe to re-run (CI checks, not releases or
deployments).
