NewInstance Documentation

Deployments (CI/CD)

Report CI/CD deployments to BugWatch so errors correlate with releases: 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 - you never send it.

@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):

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.

Lifecyclelink

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 - retrying a finish is safe.

POST/api/v1/bugwatch/deploy

Start deployment

Create a deployment record. Call at the start of your CI deploy job.

Scope: deploy:write

Body (all fields optional - an empty body is valid)

  • release - the release this deploy ships; should match what your SDK reports at runtime so errors correlate
  • meta - string map: commit, repo, branch, triggeredBy

Success - 201 Created

{ "id": "dep_64fa3c9e2b7d41c8a9f01234" }

Keep the id: every later call needs it. Status starts as in_progress.

Common errors

  • 401 - invalid/missing key
  • 403 - key lacks deploy:write
  • 404 - the project bound to this key no longer exists

Headers

x-api-key

Request body

application/json
{
  "release": "1.0.0",
  "meta": {
    "commit": "9f2c1ab",
    "repo": "acme/checkout",
    "branch": "main",
    "triggeredBy": "gitlab-ci"
  }
}

Responses

201 – Deployment created

{
  "id": "dep_64fa3c9e2b7d41c8a9f01234"
}
boltTry it
env
POSThttps://api.newinstance.cloud/api/v1/bugwatch/deploy

Headers

x-api-key

Request body

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/bugwatch/deploy' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "release": "1.0.0",
  "meta": {
    "commit": "9f2c1ab",
    "repo": "acme/checkout",
    "branch": "main",
    "triggeredBy": "gitlab-ci"
  }
}'
PATCH/api/v1/bugwatch/deploy

Report stage · finish · fail

Update a deployment. The body must contain exactly one of stage, finish, fail.

Scope: deploy:write

1 - Stage transition

{ "stage": { "key": "migrate", "name": "Run DB migrations", "status": "running" } }

status ∈ running | succeeded | failed; optional exitCode, errorSummary. Repeat per stage. A stage key is upserted - re-sending updates it.

2 - Finish

{ "finish": true }

Final status is derived from stages: any failed stage ⇒ failed, else succeeded. A failed finish opens a DeploymentFailure issue in the project.

3 - Fail explicitly

{ "fail": { "summary": "migrate exited 1", "stageKey": "migrate" } }

Success - 200 OK

{ "id": "dep_64fa3c9e2b7d41c8a9f01234", "status": "succeeded" }

Once status is no longer in_progress, further PATCHes are no-ops that echo the final status - safe to retry.

Common errors

  • 400 - stage/log limits exceeded
  • 404 - unknown deployment id (or wrong project's key)

Headers

x-api-key

Request body

application/json
{
  "stage": {
    "key": "migrate",
    "name": "Run DB migrations",
    "status": "succeeded",
    "exitCode": 0
  }
}

Responses

200 – Stage recorded

{
  "id": "dep_64fa3c9e2b7d41c8a9f01234",
  "status": "in_progress"
}
boltTry it
env
PATCHhttps://api.newinstance.cloud/api/v1/bugwatch/deploy

Headers

x-api-key

Request body

Code samples

curl -X PATCH 'https://api.newinstance.cloud/api/v1/bugwatch/deploy' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "stage": {
    "key": "migrate",
    "name": "Run DB migrations",
    "status": "succeeded",
    "exitCode": 0
  }
}'
POST/api/v1/bugwatch/deploy/logs

Append stage logs (NDJSON)

Stream a batch of log lines for one stage. Call repeatedly while the stage runs - the CLI's deploy run does this for you from the wrapped command's stdout/stderr.

Scope: deploy:write · Max body: 2 MB per batch

Body: NDJSON (one JSON object per line) or a JSON array of { level, time, message }:

  • level - Pino-style number: 10 trace · 20 debug · 30 info · 40 warn · 50 error · 60 fatal
  • time - epoch milliseconds
  • message - the log line

Deploy tags (deployId, stage) are injected server-side - do not add them yourself. Lines land in the project's normal log search.

Success - 202 Accepted

{ "ingested": 2, "skipped": 0, "deduped": 0, "truncated": false }

truncated: true means the per-deployment log cap was reached; further batches are dropped (finish/fail still work).

Headers

x-api-key

Parameters

stagequerystringdefault: Stage key these log lines belong to (required)

Request body

application/json
{"level":30,"time":{{nowMs}},"message":"Applying migration 0042_add_billing_index"}
{"level":30,"time":{{nowMs}},"message":"Migration complete in 1.2s"}

Responses

202 – Batch accepted

{
  "ingested": 2,
  "skipped": 0,
  "deduped": 0,
  "truncated": false
}
boltTry it
env
POSThttps://api.newinstance.cloud/api/v1/bugwatch/deploy/logs

Query parameters

stage

Headers

x-api-key

Request body

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/bugwatch/deploy/logs' \
  -H 'Content-Type: application/json' \
  --data-raw '{"level":30,"time":{{nowMs}},"message":"Applying migration 0042_add_billing_index"}
{"level":30,"time":{{nowMs}},"message":"Migration complete in 1.2s"}'
arrow_back
Previous
Source Maps & Symbols
Next
Support Tickets
arrow_forward