# Deployments (CI/CD)

Report CI/CD deployments to BugWatch so errors line up with the release that caused them. Every deploy shows up on the project's **Deployments** tab, its stage logs are searchable, and a failed deploy opens a `DeploymentFailure` issue automatically.

**Scope required:** `deploy:write` · **Auth:** central SECRET key (`x-api-key: {{apiKey}}`). The BugWatch environment (`production`/`staging`/…) comes from the key's resource scope, so you never send it.

## Use the CLI (recommended)

`@newinstance/bugwatch-cli` wraps all three endpoints, auto-detects CI metadata (commit, repo, branch) and persists the deployment id between steps (`.bugwatch-deploy` file or `BUGWATCH_DEPLOY_ID` env var):

```bash
export BUGWATCH_AUTH_TOKEN="sk_live_KEYID:secret"   # needs deploy:write

npx @newinstance/bugwatch-cli deploy start --release "2.4.1"
npx @newinstance/bugwatch-cli deploy run --stage migrate -- ./scripts/migrate.sh
npx @newinstance/bugwatch-cli deploy run --stage deploy  -- ./scripts/deploy.sh
npx @newinstance/bugwatch-cli deploy finish
# on failure instead:
npx @newinstance/bugwatch-cli deploy fail --summary "migrate exited 1" --stage migrate
```

`deploy run` PATCHes the stage to `running`, streams the command's stdout/stderr to the logs endpoint as NDJSON, then PATCHes `succeeded` or `failed` with the exit code.

## Lifecycle

```text
POST  /deploy                 → 201 { id: "dep_…" }        status: in_progress
PATCH /deploy/{id}            → stage transitions           { stage: { key, status, … } }
POST  /deploy/{id}/logs?stage → 202 log batches (NDJSON)
PATCH /deploy/{id}            → { finish: true }            status derived from stages
                               or { fail: { summary, stageKey } } → status: failed
```

A deployment that is no longer `in_progress` ignores further PATCHes and echoes its final status, so retrying a finish is safe.

**POST /api/v1/bugwatch/deploy**: Start deployment (fetch id `endpoint:6ae152d083f212a997c813b5`)

**PATCH /api/v1/bugwatch/deploy/{deployId}**: Report stage · finish · fail (fetch id `endpoint:6ae152d083f212a997c813b6`)

**POST /api/v1/bugwatch/deploy/{deployId}/logs**: Append stage logs (NDJSON) (fetch id `endpoint:6ae152d083f212a997c813b7`)