Skip to main content

Record a release

Post a release from your CI/CD pipeline whenever you ship. GitKraken computes deployment frequency, lead time, and change failure rate from them.

Assumes you already have a GitKraken API key — if not, see Authentication.

Creating or deleting releases requires a key issued by an organization owner or admin; listing releases also works for a manager. Other roles get 403.

Export your key for the session so the examples below can use it:

export GK_TOKEN="gk_tkn_xxxxxxxxxxxxxxxx"

Record a release​

POST /v1/insights/analytics/releases. id, repo, gitProvider and releasedAt are all required; id must be unique within the repo, and reusing one returns 400.

curl -X POST "https://api.gitkraken.dev/v1/insights/analytics/releases" \
  -H "Authorization: Bearer $GK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "v1.2.3",
    "repo": "gitkraken/gitlens",
    "gitProvider": "github",
    "releasedAt": "2026-07-09T14:30:00Z",
    "tagName": "v1.2.3",
    "headBranch": "main"
  }'

A successful create returns 201 with an empty body.

List releases​

GET /v1/insights/analytics/releases returns an organization-wide list, newest first, excluding pre-releases. Narrow it with teams, repos, orgs and lookback, or with from and to — all optional, but from and to must be supplied together; one without the other returns 400.

curl "https://api.gitkraken.dev/v1/insights/analytics/releases?repos=gitkraken/gitlens&page=1" \
  -H "Authorization: Bearer $GK_TOKEN"

Results come back under data as releases plus a totalCount — the unpaged total for the filtered window, returned even when the requested page is past the end of the results. Walk page until you've seen totalCount items.

Delete a release​

DELETE /v1/insights/analytics/releases/{id}, where {id} is the id you supplied on create — the list response does not return it. Only manually created releases can be deleted, and repo and gitProvider are required to identify the row. A deleted release no longer counts toward your metrics.

curl -X DELETE "https://api.gitkraken.dev/v1/insights/analytics/releases/v1.2.3?repo=gitkraken/gitlens&gitProvider=github" \
  -H "Authorization: Bearer $GK_TOKEN"

Returns 204 on success. An unknown id returns 404.

See the API Reference for the full request schemas and every query parameter.