Skip to main content
A 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

  1. Copy .github/workflows/route.yml from a commit of the Darkbloom actions repository into your repository as .github/workflows/darkbloom-route.yml, unchanged.
  2. 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.
  3. 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.
  4. Set the repository variable DARKBLOOM_ROUTING to exactly on. Any other value, or none, keeps every lane on its fallback without asking Darkbloom.
It is the same file for every repository. Keep it unchanged and update it by copying a newer commit.

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 read or none on the job or the workflow (read-all and 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: inherit included). Keep secrets in environments; a routed job cannot name one.
  • No environment, services, container or 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).
Pull requests from forks keep their fallback runners without asking Darkbloom.

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. Copy watchdog.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).