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

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/.27

  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/graph.py and bitrab/folder.py ↩