Guide

Ship your first tracked deployment

Connect a project, record a deployment, then use events to make every release visible.

Updated 18 Aug 2026 · 6 min

Before you begin

A project is the boundary for environments, tokens, and delivery history. Create one before automating a release.

Personal tokens are for local development. CI jobs should use a scoped service token stored by your secret manager.

shell

northstar deployments create \
+  --project prj_atlas \
+  --environment production \
+  --version 2026.08.18

Each workspace can publish 120 deployment events per minute. Northstar returns 429 with a Retry-After header when the shared limit is reached.

json

{
  "id": "dep_01J6Q6R5",
  "status": "queued",
  "environment": "production"
}

A successful create request returns a deployment ID. Poll it when a worker is offline, or subscribe to deployment.ready for the normal path.