Deploying from CI

The cleanest way to "deploy on green": your CI runs the tests and then asks the deployer to deploy, with a token that can do nothing else.

1. A token for the project

On the project's CI page, create a token with the scopes deploy and read. It works only for that project and is shown once; store it as a CI secret, e.g. DEPLOYER_TOKEN. On the server, root can also create one: sudo deployer api-token create --name ci --project shop --scope deploy,read.

2. Make pushes wait for CI (optional)

Set the project's deploy trigger to CI only (project settings). Webhook deliveries are then still verified and logged, but only your CI starts deploys.

3. Deploy from the pipeline

curl -fsS -X POST \
  -H "Authorization: Bearer $DEPLOYER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"sha\": \"$COMMIT_SHA\"}" \
  https://deploy.brakkit.com/api/v1/projects/shop/deploys

sha is optional; when given, it must be a commit on the project's branch. A deploy that is still queued is replaced by the newer one. The answer:

{"deploy_id": "…", "number": 12, "url": "https://deploy.brakkit.com/projects/shop/deploys/12", "deploy": {…}}

4. Wait for the result

curl -fsS -H "Authorization: Bearer $DEPLOYER_TOKEN" https://deploy.brakkit.com/api/v1/deploys/$ID | jq -r .state
# queued → fetching → building → starting → health_checking → switching → live
# or: failed, rolled_back, cancelled, superseded

The live log is a Server-Sent Events stream: curl -N -H "Authorization: Bearer $DEPLOYER_TOKEN" https://deploy.brakkit.com/api/v1/deploys/$ID/log.

Examples

GitHub Actions

deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - run: |
        curl -fsS -X POST \
          -H "Authorization: Bearer ${{ secrets.DEPLOYER_TOKEN }}" \
          -H 'Content-Type: application/json' \
          -d "{\"sha\": \"$GITHUB_SHA\"}" \
          https://deploy.brakkit.com/api/v1/projects/shop/deploys

GitLab CI

deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - >
      curl -fsS -X POST -H "Authorization: Bearer $DEPLOYER_TOKEN"
      -H 'Content-Type: application/json' -d "{\"sha\": \"$CI_COMMIT_SHA\"}"
      https://deploy.brakkit.com/api/v1/projects/shop/deploys

Rollback and other calls

# roll back to release r41 (scope: deploy)
curl -fsS -X POST -H "Authorization: Bearer $DEPLOYER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"release": 41}' https://deploy.brakkit.com/api/v1/projects/shop/rollback
# cancel a deploy
curl -fsS -X POST -H "Authorization: Bearer $DEPLOYER_TOKEN" https://deploy.brakkit.com/api/v1/deploys/$ID/cancel

The whole registration can be scripted as well, with a global token that has the admin scope (created on your account page).