The problem
Today each job names exactly one resource class. When that class is out of capacity, degraded, or its provider has an incident, jobs sit in the queue even while other capacity is healthy. The only workaround is editing
resource_class
in every affected repo mid-incident, then reverting it all afterwards.
  • Cloud and self-hosted capacity can't back each other up. A runner only takes jobs that name its class.
  • When a runner fleet scales too slowly for a spike, or its cluster goes down, those jobs just wait.
  • Platform teams can't plan for this in CircleCI or set it once for the whole org.
The idea
  • Having the ability to list fallback resource classes on a job, tried in order, each opening after a set wait, so the job starts wherever room opens first.
  • Fallbacks could be CircleCI cloud classes or your own runner classes, so both act as one pool.
  • Having the ability to set this once for the whole org, in the UI, API, or Terraform, so every job asking for a class follows its rule with no config change, even in repos nobody has touched in months.
Example: job-level fallbacks in config.yml
*Proposed syntax only. The
placement
key doesn't exist today.*
  • build
    : a Docker job that asks for
    acme/k8s-build
    , a self-hosted container runner class, with no
    placement
    key. An org rule can still give it fallbacks, as in the Terraform example.
  • test
    : a Docker job that asks for
    medium
    . If it hasn't started after 2m, it can also start on
    acme/k8s-small
    , a self-hosted container runner, and 2m after that on
    large
    , one size up on CircleCI cloud.
  • deploy
    : a machine job on
    ubuntu-2404:current
    that asks for
    arm.xlarge.gen2
    with
    placement: pinned
    , so it never moves.
Having the ability to define fallbacks would be really valuable.
docker:
- image: cimg/node:lts
resource_class: medium.gen2
placement:
fallback_after: 2m
fallback:
- acme/k8s-small
- large.gen1
Example: org policy and project scope in Terraform
Having an org-wide placement policy would be nice!
An org-wide placement policy:
resource "circleci_placement_policy" "acme" {
organization_id = var.circleci_org_id
}
A rule for one requested class, limited to two projects: their
acme/k8s-build
jobs can also start on Docker
large
on CircleCI cloud after 5 minutes. Other projects, such as ones that must stay on your own hardware, keep today's behavior.
resource "circleci_placement_rule" "builds" {
policy_id = circleci_placement_policy.acme.id
resource_class = "acme/k8s-build"
project_ids = [circleci_project.api.id, circleci_project.web.id]
fallback {
executor = "docker"
resource_class = "large"
after = "5m"
}
}
Guardrails
  • Jobs only move to existing classes that run them the same way, such as a Docker job to a container runner, which uses the same image.
  • placement: pinned
    keeps a job on its class, whatever the org policy says.
  • A job's own fallback list wins over the org rule, within limits the org sets.
  • No
    placement
    key and no org rule means exactly today's behavior.
  • Every move is recorded on the job and in the API, with the reason.
Who this helps
  • Anyone who would rather run a size up, or on their own runners, than wait out an incident.
  • Both Cloud-first teams with a small runner fleet as a backstop, and self-hosted-first teams with CircleCI cloud as a safety net.
  • Platform teams that want their Black Friday or disaster recovery plan for CI set up ahead of time.
  • Teams whose AI coding agents start pipelines in bursts.