> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Route workflows

> Copy the route workflow, declare lanes with their fallback labels, and keep every job runnable when Darkbloom has no capacity.

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]`.

| Field | Rule |
| - | - |
| `lane` | Lowercase letters, digits and `-`, starting with a letter or digit, at most 63 characters, unique; the key in `routes` |
| `profile` | `linux_arm64` or `macos_arm64` |
| `fallback-label` | One runner label (`[A-Za-z0-9._-]`), used whenever the lane is not routed |
| `count` | How many jobs the lane runs (its matrix size), 0 to 16, default 1. `0` keeps the fallback without asking, for jobs that will be skipped |
| `placement` | `balanced` (default) or `cheapest`. Set `count` before this optional field. `cheapest` chooses the lowest compute price among eligible Macs, including provider discounts |
| `shape` | Optional `<vCPUs>x<memory GiB>`, decimal without leading zeros: 1–256 vCPUs and 1–1024 GiB. Set `count` and `placement` before it. The size needs a published signed sibling and a priced runner class |

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:

| Profile | `runs-on` on Darkbloom |
| - | - |
| `linux_arm64` | `[self-hosted, linux, ARM64, darkbloom-linux-arm64]` |
| `macos_arm64` | `[self-hosted, macOS, ARM64, darkbloom-macos-arm64]` |

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:

```yaml theme={null}
permissions:
  contents: read

jobs:
  route:
    name: Route
    uses: ./.github/workflows/darkbloom-route.yml
    permissions: {}
    with:
      lanes: |
        test linux_arm64 ubuntu-24.04-arm 2
        lint linux_arm64 ubuntu-24.04-arm
        macos macos_arm64 macos-15

  test:
    name: Test (shard ${{ matrix.shard }})
    needs: route
    runs-on: ${{ fromJSON(needs.route.outputs.routes)['test'] }}
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Test
        run: make test SHARD=${{ matrix.shard }} SHARDS=2

  lint:
    name: Lint
    needs: route
    runs-on: ${{ fromJSON(needs.route.outputs.routes)['lint'] }}
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Lint
        run: make lint

  macos:
    name: macOS build
    needs: route
    runs-on: ${{ fromJSON(needs.route.outputs.routes)['macos'] }}
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Build and test
        run: swift test
```

`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:

| Decision | Why |
| - | - |
| `routing is off` | `DARKBLOOM_ROUTING` is not exactly `on` |
| `pull request from a fork` | Forks keep their fallback runners; nothing is asked |
| `not requested` | The lane's count is 0 |
| `plane URL is not https` | `DARKBLOOM_SANDBOX_URL` does not start with `https://` |
| `run identity is unavailable` | The run ID or attempt is not numeric |
| `plane request failed (HTTP <status>)` | Darkbloom did not answer 200 within 5 seconds; status `000` is a network error. A timeout, 408, 429 or 5xx is retried once |
| `plane reply is malformed` | The answer is not one route |
| `plane: <reason>` | Darkbloom chose the fallback: for example `repository_not_approved`, `payer_not_authorized`, `monthly_spend_cap`, `no_capacity`, `paused` or `run_fallback_forced` (an earlier attempt of the run stranded on Darkbloom and was rescued) |
| `plane decision is missing or invalid` | The answer did not repeat the requested profile and placement labels exactly |

The per-reason answers are in [troubleshooting](https://docs.darkbloom.dev/ci/troubleshooting.md).

## Configuration

| Repository variable | Meaning |
| - | - |
| `DARKBLOOM_ROUTING` | `on` asks Darkbloom; anything else keeps every fallback |
| `DARKBLOOM_SANDBOX_URL` | Optional; default `https://api-sandbox.darkbloom.dev`. Must be `https://` |

## 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.

| Repository variable | Meaning |
| - | - |
| `DARKBLOOM_WATCHDOG` | `off` turns it off; anything else (or unset) keeps it on |
| `DARKBLOOM_WATCHDOG_MINUTES` | Optional; how long a Darkbloom job may wait for a runner, 15 to 1440 (default 30) |
| `DARKBLOOM_ROUTE_JOB` | Optional; the route job's name (default `Select Runners`) |
| `DARKBLOOM_APP_SLUG` | Optional; the Darkbloom App whose markers it honours (default `darkbloom-sandbox`) |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.