Skip to content

Running pipelines

Basic usage

Run from the directory that contains your .gitlab-ci.yml or .bitrab-ci.yml:

bitrab

or explicitly:

bitrab run

If both files exist, bitrab prefers .bitrab-ci.yml unless you pass -c explicitly.12

Pick a config file

bitrab run -c path/to/my-ci.yml

Dry run

bitrab run --dry-run

Dry run shows what would execute without launching job scripts.2

Parallel execution

bitrab run --parallel 4

In stage mode, jobs in the same stage can run concurrently. In DAG mode, jobs are released as soon as their needs: dependencies are satisfied. For real runs in a Git checkout, parallel jobs use per-job git worktrees by default when they can. Use --serial when jobs need to mutate the real working tree instead of an isolated checkout.42

Filters

Run only named jobs:

bitrab run --jobs lint test

Run only selected stages:

bitrab run --stage build test

You can combine both. Unknown names generate warnings instead of crashing.32

CI-friendly output

bitrab run --no-tui

Bitrab uses a Textual TUI in interactive mode, but plain output is usually the better choice for CI logs, shell transcripts, and LLM-driven sessions. CI mode also disables the TUI automatically when CI=true is present.25

Run bitrab inside CI

One of bitrab's more interesting uses is running it inside a single CI job:

local_ci:
  script:
    - pipx install bitrab
    - bitrab run --no-tui --parallel 4

That lets one container or VM execute several pipeline jobs in parallel, which can reduce queueing and repeated environment setup compared with splitting every small task into a separate remote CI job. It is not identical to native GitLab fan-out, but it can save build minutes when isolation is unnecessary.43

Changed jobs (--changed)

bitrab run --changed
bitrab run --changed --incremental --no-tui
bitrab run --changed --changes-base origin/develop

Changed-job selection uses the same committed-plus-working-tree baseline described in Local vs GitLab. Jobs with matching fingerprint or rules:changes patterns run, as do jobs without declared inputs and transitive needs: dependents. Combining it with --incremental lets unchanged fingerprints skip even within that conservative selection.

Install that fast path before every push with bitrab install-hook.

Incremental runs (--incremental)

bitrab run --incremental

With --incremental, bitrab skips any job whose fingerprint matches its last successful run — a Turborepo-style memoization for pipelines, with no containers. Skipped jobs are reported with a distinct cached status and counted separately in the summary. Memoized jobs still satisfy needs: and their previously collected artifacts under .bitrab/artifacts/<job>/ are still injected into downstream jobs; if that artifact directory is gone, the job runs again. This is always opt-in — without the flag, nothing changes.7

What the fingerprint sees

A job's fingerprint is a SHA-256 digest over:

  1. The resolved before_script, script, and after_script.
  2. The job's variables: (resolved values).
  3. The values of environment variables you declare in pyproject.toml:

toml [tool.bitrab] fingerprint_env = ["CC", "TOOLCHAIN_HOME"]

This is an explicit salt for shared-environment inputs (toolchain paths, compiler versions) that scripts read but bitrab cannot infer. 4. A content digest of the job's input files. Precedence: - variables: BITRAB_FINGERPRINT_PATHS: "src/**,pyproject.toml" (comma-separated globs) — explicit wins; - cache: key: files: entries; - fallback: all git-tracked files, using git's own blob hashes (git ls-files -s) plus a hash of git diff for dirty working-tree state — nothing is re-hashed. Outside a git repository the fallback is inert: only scripts, variables, and explicitly declared paths are fingerprinted. 5. The fingerprints of every job this one needs:/depends on — an upstream change transitively re-runs downstream jobs. 6. The bitrab version and a schema version, so upgrades invalidate cleanly.

What the fingerprint does NOT see

The outside world. Network resources, system package upgrades, tool installs, database state — none of these change the fingerprint, so a "cached" job may be stale if its behaviour depends on them. Escape hatches:

  • bitrab run --incremental --refresh — run everything, record fresh fingerprints;
  • bitrab clean --what fingerprints — drop the store entirely.

Untracked files are also invisible to the git fallback; declare them via BITRAB_FINGERPRINT_PATHS if a job depends on them.

Only successful jobs record a fingerprint; failed jobs (and jobs flagged by mutation detection) always re-run. bitrab run --dry-run --incremental reports which jobs would be memoized without touching the store. The store lives at .bitrab/fingerprints/ under the project root and is safe against concurrent runs.

Watch mode

bitrab watch

Watch mode reruns the pipeline when the root config file or any local include file changes.6

Logs, graph, and cleanup

bitrab logs
bitrab graph
bitrab clean --dry-run

Run logs are stored under .bitrab/logs/, graph output can be rendered as text or Graphviz DOT, and cleanup commands remove artifacts, job directories, and logs under .bitrab/.28

  1. Source: bitrab/config/loader.py ↩

  2. Source: bitrab/cli.py ↩↩↩↩↩↩

  3. Source: bitrab/plan.py ↩↩

  4. Source: bitrab/execution/stage_runner.py ↩↩

  5. Source: bitrab/tui/orchestrator.py and bitrab/tui/ci_mode.py ↩

  6. Source: bitrab/watch.py ↩

  7. Source: bitrab/execution/fingerprint.py ↩

  8. Source: bitrab/graph.py and bitrab/folder.py ↩