CI Workflows

CI is built into rbs. Workflows are declared in the RBS language — the same language as your build files — and executed by the rbs DAG engine: independent jobs run in parallel, needs edges order the rest, and every step benefits from the shared cache. There is no YAML dialect and no separate runner to install; the rbs binary that builds your workspace also runs its CI.

Defining a workflow

Declare workflows with ci_workflow() in a file named ci.rbs. rbs discovers every ci.rbs in the workspace (workflows can also live in WORKSPACE.rbs), so a monorepo can keep each service’s pipeline next to its code.

ci_workflow(
    name = "main",
    on = {
        "push": {"branches": ["main"]},
        "pull_request": {"branches": ["main"]},
    },
    jobs = {
        "build": {
            "steps": [
                {"name": "Build everything", "run": "rbs build //..."},
            ],
        },
        "test": {
            "needs": ["build"],
            "steps": [
                {"name": "Test everything", "run": "rbs test //..."},
            ],
        },
    },
)

Jobs form a DAG: test waits for build, and jobs without edges between them run concurrently. A dependency cycle is rejected before anything runs.

Triggers

The on dict declares which events run the workflow:

push — filter with branches, branches_ignore, tags, tags_ignore, paths, paths_ignore. Glob patterns work ("v*", "release/**"). A workflow that only declares tags runs only on tag pushes; one that only declares branches runs only on branch pushes.
pull_request — filter with branches (the target branch), branches_ignore, types, paths, paths_ignore.
manual — runs only when invoked by name or with --event manual.
schedule — {"cron": "0 6 * * *"}. rbs does not run a daemon; a schedule trigger matches when an external scheduler invokes rbs ci run --event schedule.

Path filters compare against the files changed since the base ref, so a docs-only push can skip a build workflow entirely.

Steps

Each job runs its steps in order. A step is one of four kinds:

Key	What it does	Example
`run`	Runs a shell command (bash by default; override with `shell`)	`{"run": "rbs infra apply -y -e dev"}`
`rbs`	Runs an rbs command	`{"rbs": "build //..."}`
`target`	Builds, tests, or covers one label	`{"target": "//services/api:test", "command": "test"}`
`affected_target`	Runs a target name across every affected package that defines it	`{"affected_target": "test", "command": "test"}`

For target and affected_target steps, command selects the rbs verb: "build" (the default), "test", or "coverage". Steps also accept name, env, if, working_directory, timeout, and continue_on_error (a failing step with continue_on_error set does not fail the job).

Environment variables

Steps see your environment plus three layers of declared variables — workflow-level env, then job-level, then step-level, later layers overriding earlier ones. rbs adds the trigger context automatically:

CI_EVENT_TYPE — push, pull_request, manual, …
CI_REF — the fully-qualified ref (refs/heads/main, refs/tags/v1.2.0)
CI_BRANCH — the branch name
CI_PR_NUMBER — set for pull-request runs

Conditions

Jobs and steps take an if expression. The evaluated forms are always(), success(), failure(), cancelled(), and the literals true / false.

An if expression the engine does not recognize is treated as true — the job runs. Keep conditions to the supported forms.

Matrix jobs

A job with a matrix expands into one job per combination:

"test": {
    "matrix": {
        "go": ["1.21", "1.22"],
        "os": ["linux", "darwin"],
    },
    "steps": [
        {"name": "Test", "run": "rbs test //..."},
    ],
},

This produces four jobs, scheduled in parallel like any other independent jobs. Each expansion’s variable assignment is recorded in the run results and shown by rbs ci plan.

Running workflows

# Run every workflow matching a push to the current branch
rbs ci run --event push

# Run one workflow by name
rbs ci run main

# Simulate a pull request
rbs ci run --event pull_request --base main --pr 42

# A tag push (release workflows)
rbs ci run --event push --tag v1.2.0

With no workflow name, every workflow whose triggers match the event runs. The trigger context comes from flags first and the workspace’s git state otherwise — --event, --branch, --tag, --ref (a fully-qualified ref decides branch vs tag), --base, and --pr. Useful flags on rbs ci run:

--workers N — parallel job slots (default 4)
--timeout 30m — overall workflow timeout
--fail-fast — stop at the first failing workflow (default on)
--json — emit run results as JSON
--remote host:port — run the jobs on a remote cluster (see below)

Inspecting workflows and runs

rbs ci list                 # every workflow, its triggers and job DAG
rbs ci trigger              # the trigger context git currently implies
rbs ci status               # recent runs (newest first)
rbs ci status <run-id>      # one run: jobs, steps, errors

Run records persist in the workspace, so rbs ci status sees runs from earlier invocations; the most recent 50 are kept.

Planning without running

rbs ci plan resolves a trigger event into the exact job DAG it would execute and prints it as JSON on stdout — nothing runs, nothing is written:

rbs ci plan --event push --branch main
rbs ci plan --event pull_request --base main --pr 42

Matrix jobs are expanded and needs edges are rewritten to the expanded names, so the output is the DAG that would actually be scheduled. This is the integration point for external schedulers and dashboards.

Affected-package detection

For monorepos, rbs can compute which packages the current change actually touches — directly and through the dependency graph:

rbs ci affected                  # packages affected vs the base ref
rbs ci affected --base main      # explicit base
rbs ci affected --json --verbose

Inside a workflow, an affected_target step applies this automatically: it finds every affected package defining the named target and runs just those, instead of the whole workspace.

"quick-check": {
    "steps": [
        {"name": "Test what changed", "affected_target": "test", "command": "test"},
    ],
},

Running CI on a cluster

If you run a remote build cluster (see Remote cache & execution), rbs ci run can fan the workflow’s jobs onto its workers instead of running them locally:

rbs ci run --remote host:8980
# or, with $RBS_REMOTE set, pass the bare flag:
rbs ci run --remote

Each job is submitted to the cluster with its needs edges preserved as job dependencies. Workers check out the repository at the triggering commit, stream their logs back to your terminal, and any rbs commands inside the job’s steps automatically use the same cluster — so every job shares one cache.

Fleet CI submits jobs with the CI_* context variables, but secret values are never placed in job specs — a job spec can sit in the queue, and secrets do not belong there. See the secrets rule.

Getting Started

Build

Languages

Containers & Deploy

Infrastructure

CI & Remote Builds

Team Workflow

Defining a workflow

Triggers

Steps

Environment variables

Conditions

Matrix jobs

Running workflows

Inspecting workflows and runs

Planning without running

Affected-package detection

Running CI on a cluster

​Defining a workflow

​Triggers

​Steps

​Environment variables

​Conditions

​Matrix jobs

​Running workflows

​Inspecting workflows and runs

​Planning without running

​Affected-package detection

​Running CI on a cluster

Defining a workflow

Triggers

Steps

Environment variables

Conditions

Matrix jobs

Running workflows

Inspecting workflows and runs

Planning without running

Affected-package detection

Running CI on a cluster