kogutdocs

    Type to search page titles, headings and text.

    Deploys

    Deploy API

    Request fields, authentication, and responses for recording deploys.

    POST /api/deploys records a deploy for an existing service. It needs a bearer token with the deploy scope, created in Settings → Tokens. The token is shown once; keep it in your CI secrets. Record other changes, such as migrations, with the Change API.

    Request

    curl -fsS -X POST https://kogut.acme.com/api/deploys \
  -H "Authorization: Bearer $KOGUT_TOKEN" \
  -d service=api -d version="$GITHUB_SHA"

    The body limit is 64 KiB. Content-Type: application/json selects JSON. Other content types are parsed as form fields.

    FieldRequiredMeaning
    serviceYesExisting kogut service name
    versionYesCommit hash, tag, or version string
    byNoPerson or system that deployed
    urlNoLink shown with the deploy
    descriptionNoDescription shown on the timeline

    Each field allows at most 500 characters. Empty optional fields count as absent. Unknown service names do not create services.

    The deploy time is when kogut receives the request, so call it after the version goes live. Send one request per service. Deploys of a dependency also count in correlation.

    The agent records a deploy, with source agent, when a container starts from a new image; see Container images.

    Responses

    Deploys with the same service and version within 2 min merge, including events from GitHub. A new deploy returns 201 with {"event_id": 42, "merged": false}. A merged request returns 200 with merged: true.

    StatusMeaning
    201New deploy recorded
    200Merged with a deploy from the last 2 min
    400Unreadable body, unknown field, or JSON missing service or version
    401Missing or invalid bearer token
    403Token lacks the deploy scope
    413Body exceeds 64 KiB
    422Empty required value, field over 500 characters, or unknown service
    503Server busy or storage wait exceeded. A retry can merge with a stored deploy.

    Shell example

    The final || keeps a failed call from failing the deploy.

    deploy.sh
    #!/bin/sh
set -eu

version=$(git rev-parse --short HEAD)
docker compose pull api && docker compose up -d api
curl -fsS -X POST https://kogut.acme.com/api/deploys \
  -H "Authorization: Bearer $KOGUT_TOKEN" \
  -d service=api -d version="$version" \
  || echo "kogut: could not mark the deploy" >&2