CI/CD ingestion

Mint an ingestion tokenCopy Anchor Link

Open Account Settings → API Tokens and press Create Token. Name it after the pipeline, confine it to the project the pipeline deploys, and tick ci:deploy and nothing else. The ability satisfies the deployment writes alone: the token can record and finish deployments, and every read, every other write and every other project is refused. The deployments it records are written as you, so mint it as the release manager or as a service account the team keeps for the purpose. Put the plaintext in the pipeline's secret store; it is shown once. API tokens covers the page in full.

You will also need the project's id and the environment's id, both in the address bar of their pages and in the GET /v1/projects/{project}/environments answer; keep them beside the token as pipeline variables.

Report a deployment in one callCopy Anchor Link

A pipeline that reports after the deployment is done sends one request:

curl -sS -X POST "$BIFROST_API/v1/projects/$BIFROST_PROJECT/deployments" \
  -H "Authorization: Bearer $BIFROST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $PIPELINE_RUN_ID" \
  -d '{
        "environment_id": "'"$BIFROST_ENVIRONMENT"'",
        "version": "1.4.0",
        "commit_sha": "'"$COMMIT_SHA"'",
        "branch": "main",
        "pipeline_url": "'"$PIPELINE_URL"'"
      }'

The status is succeeded when left out; send "status": "failed" from the failure branch of the job and the record is kept as a failure. The answer is 201 with the deployment, and the environment now carries the version as its Current Version.

Report as the deployment starts and endsCopy Anchor Link

A pipeline that reports as it goes opens the deployment first, deploys, then finishes it whichever way the job ended:

DEPLOYMENT_ID=$(curl -sS -X POST "$BIFROST_API/v1/projects/$BIFROST_PROJECT/deployments" \
  -H "Authorization: Bearer $BIFROST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $PIPELINE_RUN_ID-start" \
  -d '{"environment_id": "'"$BIFROST_ENVIRONMENT"'", "version": "1.4.0", "status": "running", "commit_sha": "'"$COMMIT_SHA"'", "branch": "main", "pipeline_url": "'"$PIPELINE_URL"'"}' \
  | jq -r '.data.id')

curl -sS -X PATCH "$BIFROST_API/v1/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $BIFROST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $PIPELINE_RUN_ID-finish" \
  -d '{"status": "succeeded"}'

Send failed or cancelled instead when the job ended that way; a finish step that always runs, reading the job's own outcome, is the shape the ready-made snippets use. A deployment finished once is not moved again, so a second finish, from a retried job, answers 422 and changes nothing.

Keep retries harmlessCopy Anchor Link

Every write needs an Idempotency-Key. Use the pipeline's run id, with a suffix per step when a run makes more than one call: a retried step with the same key and the same body receives the first answer again, so a flaky network records nothing twice, while the same key with a different body is refused. The rules are on the idempotency page.

Or let GitHub deployments report themselvesCopy Anchor Link

A GitHub workflow that creates deployments through GitHub's own Deployments API, on a repository picked from the team's App installation, needs no step: the App hears each deployment and each of its statuses and records them on the environment whose name matches. The matching and the version rules are on CI and deployments.