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. Schedule a scan¶

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

Response (201 Created):

{
  "id": "task-1786482521535742990",
  "repo_url": "https://github.com/golang/example",
  "ref": "HEAD",
  "status": "queued",
  "engine": "local",
  "attempt": 0,
  "max_attempts": 3,
  "created_at": "2026-08-11T12:00:00Z",
  "updated_at": "2026-08-11T12:00:00Z"
}

5. 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.

6. 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
}

7. (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/..."

→ Repo command for repo config options.