kogutdocs

    Type to search page titles, headings and text.

    Deploys

    GitHub

    Record deploys from GitHub events through a signed webhook.

    A GitHub webhook records deploys without changes to your CI workflow.

    Set it up

    1. Generate a random secret, for example with openssl rand -hex 32. Set it in the environment and map the repository to an existing kogut service:

      kogut.toml
      [github]
secret = "${GITHUB_WEBHOOK_SECRET}"

[[github.repo]]
name = "acme/api"
service = "api"

      Repository names are case-insensitive. kogut reloads the file automatically.

    2. On GitHub, open Settings → Webhooks → Add webhook. Enter https://kogut.acme.com/hooks/github, select application/json, and paste the same secret. Exempt /hooks/github from any sign-in proxy.

    3. Select the events that match when your code goes live:

      • push records non-deletion pushes to the default branch, using the full head hash, pusher, and commit link.
      • release records published, non-draft releases, using the tag, author, and release link.
      • deployment_status records successful production deployments, using the commit, deployment creator, and environment URL. Use it when a push does not mean the release is live; see Deployments.

    4. Under Recent Deliveries, check that GitHub’s initial ping receives 204. After a matching event, check the service’s Deploys card.

    For an organisation webhook, add a mapping for each repository. To record several services from one repository, repeat [[github.repo]] with the same name and a different service. If only some services change, use the deploy API from CI.

    Deployments

    GitHub sends deployment_status for GitHub Actions jobs that set environment:, and for hosts that report through GitHub’s Deployments API, such as Vercel. The repository’s Deployments list shows each environment name.

    By default, kogut records a deployment only when GitHub marks its environment as production or it is named production in any case. Preview deployments are skipped.

    To record another environment, name it on the mapping. Only deployments to that environment, in any case, are then recorded for that service. push and release events are not affected.

    kogut.toml
    [[github.repo]]
name = "acme/api"
service = "api"

[[github.repo]]
name = "acme/api"
service = "api-staging"
environment = "staging"

    If your production environment has another name, such as live, and GitHub does not mark it as production, set environment = "live".

    Fix failed deliveries

    • 404: add the [github] section.
    • 401: check the shared secret. Every request needs an HMAC-SHA256 signature in X-Hub-Signature-256.
    • 400: check that the JSON body matches the event.
    • 422: add the repository mapping.

    Ignored events return 204. Recorded events return 201, or 200 when merged with a recent deploy (merge rules).

    If CI also calls the API, send the full commit hash, such as $GITHUB_SHA. A short hash does not match GitHub’s version, so the two do not merge.