Quick Start

This takes you from a running binary to a completed scan with a stored result.

1. Configure

Configuration is read from .go-crap-tracker.yaml (project root or $HOME) and from GCTD_-prefixed environment variables. Sensible defaults apply, so the minimum to get moving is a Postgres DSN and a NATS URL.

.go-crap-tracker.yaml:

loglevel: info
logformat: json
worker_engine: local
max_stale_min: 10
crap_bin: "go-crap"
nats_url: "nats://localhost:4222"
dsn: "postgres://postgres:postgres@localhost:5432/crap_tracker?sslmode=disable"
server:
  host: "0.0.0.0"
  port: 8080
cache:
  directory: "./cache"
  lock_lease: 30s
  lock_wait: 10m
  test_timeout: 10m
  coverage_keep: 10

Or via environment:

export GCTD_NATS_URL=nats://localhost:4222
export GCTD_DSN=postgres://postgres:postgres@localhost:5432/crap_tracker?sslmode=disable
export GCTD_CACHE_DIRECTORY=./cache

→ Configuration for the full reference.

2. Start the control plane

./go-crap-tracker serve

On startup it opens Postgres, runs the SQL migrations, ensures the NATS stream and durable consumer, and starts the HTTP server, the reconciler, and the NATS→SSE bridge.

3. Start a worker

./go-crap-tracker worker

The worker subscribes to the job queue and waits for messages.

4. Register the repo

curl -X POST http://localhost:8080/api/repos \
  -H 'Content-Type: application/json' \
  -d '{"repo_url": "https://github.com/golang/example"}'

or via the CLI:

./go-crap-tracker repo add https://github.com/golang/example

Response (202 Accepted): the repo record with Status: "registering". A worker clones the repo and discovers its Go projects, then the status flips to ready:

./go-crap-tracker repo show https://github.com/golang/example
# repo:      https://github.com/golang/example
# status:    ready
# commit:    1234567890ab
# projects:  -              # single-module repo: only the root project

5. Schedule a scan

curl -X POST http://localhost:8080/api/repos/analyze \
  -H 'Content-Type: application/json' \
  -d '{"repo_url": "https://github.com/golang/example"}'

or via the CLI (--project scopes a multi-module repo to one project):

./go-crap-tracker repo analyze https://github.com/golang/example
# queued task task-… project= ref=""

Response (202 Accepted): the queued task(s) — one per project of the repo. The legacy POST /api/tasks still works and delegates to the same analyzer.

6. Watch it run

Open the web UI at http://localhost:8080/, or poll:

curl http://localhost:8080/api/tasks/task-1786482521535742990

Status will move queued → running → completed. When completed it carries an analysis_id.

7. Read the result

curl http://localhost:8080/api/tasks/task-1786482521535742990/result

{
  "id": "a3f2c8d1e9b04f7a",
  "repo_info": {
    "url": "https://github.com/golang/example",
    "ref": "HEAD",
    "commit_sha": "abc123"
  },
  "summary": { "average": 42.5, "combined": 85.0, "exceeded": 3, "total_funcs": 24 },
  "engine": "local",
  "crap_version": "v0.5.1",
  "analyzed_at": "2026-08-11T12:00:05Z",
  "duration_ms": 4500
}

8. (Optional) Pin a branch or tune the scan

# Track a specific branch and pass custom go test args
./go-crap-tracker repo config set https://github.com/org/repo \
  --ref release \
  --test-args "-race ./pkg/..."

# Same, but scoped to one project of a multi-module repo
./go-crap-tracker repo config set https://github.com/org/monorepo \
  --subdir tsc \
  --test-args "-race ./..."

→ Repo command for repo config options.