Getting started

Quickstart

Run the gate end to end on the included fixture, then scaffold Riven into a real GitLab repository.

1. Clone and install

bash

git clone git@gitlab.com:pavilion4/blast-radius.git
cd blast-radius
npm install

2. Build and verify the included fixture

bash

npm run build
npm run verify

That rebuilds the demo-repo, validates the sample contract, runs the test suite, and proves the planted breaking change fails the gate.

Use the fixture first

The fastest way to understand Riven is to watch it fail on a controlled breaking change before wiring it into a live repository.

3. Scaffold a target repository

From the repository you want to protect:

bash

blast-radius-governor init --repo .
blast-radius-governor init --repo . --apply

This writes:

.governor.yml
.gitlab-ci.yml

4. Validate readiness

bash

blast-radius-governor doctor --repo .

doctor checks Git history, Orbit availability, config shape, CI assumptions, and whether the GitLab gate can run with the current repo state.

5. Run the gate locally

bash

blast-radius-governor gitlab-gate --repo . --config .governor.yml --output risk-contract.yaml

When required conditions are unmet, the command exits non-zero and writes the same contract artifact GitLab CI enforces.

6. Bootstrap the GitLab project

bash

blast-radius-governor gitlab-bootstrap \
  --project group/project \
  --check-ci-variable GITLAB_TOKEN

To apply changes:

bash

GITLAB_TOKEN=<project-access-token> \
  blast-radius-governor gitlab-bootstrap \
    --project group/project \
    --check-ci-variable GITLAB_TOKEN \
    --apply

Next: Installation & setup.