Skip to content

Quick start

This guide gets you from install to a useful local CI loop quickly.

1. Install bitrab

pipx install bitrab

If you want the native speedups:

pipx install 'bitrab[fast]'

Or for this repository while developing:

uv sync --all-extras
uv run bitrab --version

2. Validate your pipeline

bitrab validate

This checks the YAML against GitLab's schema, then reports features that bitrab handles differently locally.1

3. Run the pipeline locally

bitrab run --no-tui --parallel 1

That is the safest starting point: plain output and one job at a time in the real workspace.23

4. Speed it up when jobs are independent

bitrab run --no-tui --parallel 4

Jobs in the same stage can run concurrently, and DAG pipelines can also release work as dependencies complete. For real runs in a Git checkout, bitrab uses per-job git worktrees by default when it can, so parallel jobs do not stomp on the same files.3

If a job is supposed to mutate your real checkout, keep it serialized instead:

bitrab run --no-tui --serial

5. Run only part of the pipeline

bitrab run --jobs lint test
bitrab run --stage build test

This is useful for short local feedback loops while keeping .gitlab-ci.yml as the source of truth.2

6. Enable mutation warnings for read-only jobs

Add this to pyproject.toml:

[tool.bitrab]
warn_on_mutation = true

[tool.bitrab.mutation]
whitelist = ["docs/**"]

When enabled, bitrab snapshots the project tree before a job and warns if the job creates or modifies files outside the built-in and custom whitelist.4

7. Try the dogfooding command

In this repository, the local CI loop is:

uv run bitrab run --no-tui --parallel 1

8. Useful next commands

bitrab watch
bitrab graph
bitrab logs
bitrab clean --dry-run

  1. Source: bitrab/cli.py and bitrab/config/validate_pipeline.py ↩

  2. Source: bitrab/cli.py ↩↩

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

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