Tell Status about deploys

Get a server secret

Every call is made with one of the project's server secrets, which start with sk_, sent as Authorization: Bearer sk_…. Keep it in the server's environment as MYBEAST_STATUS_SECRET.

• When the project has Secrets, id.my-beast.com made one with the project, and Secrets keeps MYBEAST_STATUS_URL and MYBEAST_STATUS_SECRET in each environment. A deploy that takes its .env from Secrets has them already.
• Otherwise, an admin makes one in Status's Settings, under Status keys, with New Status key. It's shown once, so a sign-in at id.my-beast.com within the last 15 minutes is asked first. Make one per deploy or script, and revoke it there when it's no longer used.

MYBEAST_STATUS_URL is the project's address in Status, for people. The calls on this page go to https://services.my-beast.com/status/api/v1.

Say when a deploy goes live

curl -fsS -X POST https://services.my-beast.com/status/api/v1/deploys \
  -H "Authorization: Bearer $MYBEAST_STATUS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"environment": "production", "phase": "live", "ref": "abc1234"}'

{
  "id": 31,
  "environment": "production",
  "checks_due": 4
}

With "phase": "live", that environment's HTTP checks run at once, within 15 seconds, and on every run for 5 minutes after. checks_due is how many. A down in the 15 minutes after names the deploy in its alert, such as "Right after abc1234 went live", so the first question is answered.

ref is yours: a commit, a tag, a release number. "phase": "started" records that a deploy began, without checking anything. The project's overview lists the latest deploys with what the checks said after each.

Keep the deploy quiet

A restart can fail a check or two. A maintenance window around the deploy keeps those blips from waking anyone, and a down still going when it ends is told then. Put it together like this:

# In the deploy script, with MYBEAST_STATUS_SECRET in its environment.
api=https://services.my-beast.com/status/api/v1
auth="Authorization: Bearer $MYBEAST_STATUS_SECRET"

curl -fsS -X POST $api/maintenance -H "$auth" -H "Content-Type: application/json" \
  -d '{"minutes": 10, "note": "Deploying", "environment": "production"}'

./release.sh   # your deploy

curl -fsS -X POST $api/maintenance/end -H "$auth"
curl -fsS -X POST $api/deploys -H "$auth" -H "Content-Type: application/json" \
  -d "{\"environment\": \"production\", \"phase\": \"live\", \"ref\": \"$(git rev-parse --short HEAD)\"}"

Plan maintenance explains windows. Add || true to a call if the deploy should go on when Status can't be reached.

Keep monitors in code

A deploy can send the project's whole list of monitors each time, and Status adds, changes or removes monitors to match it. The monitors then live in your repository, reviewed like the rest of your code.

curl -fsS -X PUT https://services.my-beast.com/status/api/v1/monitors \
  -H "Authorization: Bearer $MYBEAST_STATUS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"monitors": [
    {"key": "api", "name": "API", "type": "http", "url": "https://api.example.com/up", "public": true},
    {"key": "backup", "name": "Nightly backup", "type": "heartbeat", "every_minutes": 1440, "grace_minutes": 60}
  ]}'

{
  "monitors": [
    {
      "key": "api",
      "id": "9d1c4a7e-5b2f-4e8a-9c3d-2f6b8a1e7c40",
      "type": "http",
      "environment": "production",
      "state": "waiting"
    },
    {
      "key": "backup",
      "id": "9d1c4a7f-0c3e-4f1b-8a2d-6e5f4c3b2a10",
      "type": "heartbeat",
      "environment": "production",
      "state": "waiting",
      "ping_url": "https://services.my-beast.com/status/ping/abc123def456ghi789jkl012"
    }
  ],
  "added": 2,
  "changed": 0,
  "removed": 0
}

The answer lists each monitor of the list with its state, and for a heartbeat its ping_url: the address its job calls. Every field a monitor can have is in Sync the monitors.

How the list is matched

• Each monitor's key finds it again. A new key is added, a known one is changed to match, and a key no longer listed is removed.
• Monitors added on their pages have no key, and the list never touches them. A change made on the page to a monitor with a key is put back by the next list.
• The same list twice changes nothing, so a deploy can send it every time.
• A list with a mistake is refused whole, and nothing changes. So is one that doesn't fit the plan's monitors, counting the ones added by hand and every one listed: swapping one monitor for another at the limit fits.
• A list has at most 200 monitors.