Mark releases from CI or your host
Last updated
A release marks the moment your site or app changed. Metrickle shows releases on the Overview chart, adds the latest one to alerts, and judges each protected task since the latest release. This page covers recording releases automatically. For what releases do in the dashboard, see releases.
There are three ways a release gets recorded:
- New app versions, automatically. When events arrive with an app version Metrickle hasn’t seen before (
appVersionin the SDK options, orcontext.app.versionover the HTTP ingest API), it becomes a release, dated when it was first seen. This is checked every hour. The mobile SDKs send the version for you. On the web only the npm package can setappVersion: the script tag can’t, so sites that load it need the deploy hook. - The deploy hook, from CI or your hosting provider. Best for websites, which don’t have an app version.
- By hand, in the dashboard under Integrations → Releases → Add release, or from an assistant with the
create_releaseMCP tool. This needs thereleases.managepermission.
Get the deploy hook URL
Open the app’s Integrations page and choose Set up deploy hook under Releases. Only owners and admins, or people with the apps.keys permission, can see it. The URL looks like this:
https://in.metrickle.com/v1/releases/rh_…
The URL is the credential: anyone with it can add releases to the app. Keep it in your CI secrets. If it leaks, choose Replace URL. The old URL stops working straight away.
Send a release from CI
Add a step after each production deploy:
curl -X POST "$METRICKLE_DEPLOY_HOOK" \
-H "content-type: application/json" \
-d '{"version": "4.12", "description": "New sign-up form", "url": "https://quillmere.example/changelog/4.12"}'
| Field | Required | What it is |
|---|---|---|
version | Yes | The version, tag or commit |
description | No | Up to 500 characters |
url | No | A link to release notes or the deploy |
environment | No | Such as production |
The same fields work as a form post (version=4.12) or in the query string (?version=4.12).
Point GitHub, Vercel or Netlify at it
You can paste the same URL into your host’s webhook settings without changing anything. Metrickle reads each one’s own format and ignores pings, failed deploys and preview deploys.
| Sender | Set up | Recorded |
|---|---|---|
| GitHub | Settings → Webhooks, content type application/json, events Releases and/or Deployment statuses | Published releases (not drafts or pre-releases), with the tag as the version. Successful deployments to environments that aren’t preview, staging, development or test, with the deployed ref as the version when it looks like one (v1.4.0, 2.0), otherwise the short commit |
| Vercel | Settings → Webhooks, event Deployment Succeeded | Production deployments only, with the short commit (or the deployment id) as the version |
| Netlify | Site configuration → Notifications → Outgoing webhook, event Deploy succeeded | Deploys that aren’t previews or branch deploys, with the short commit (or the deploy id) as the version |
Each URL belongs to one app. If one repository deploys more than one app (a website and a web app, say), a repository webhook sends every deploy to the same app, so post from each app’s deploy step instead.
The same version sent again within 10 minutes is kept once (unless it names a different commit), so a sender that posts twice doesn’t leave a release that can never be judged.
Responses
| Status | Body | Means |
|---|---|---|
201 | { "ok": true, "recorded": true, "release": {...} } | A release was added |
200 | { "ok": true, "recorded": false } | Read, but not a release: a ping, a failed or preview deploy, or no version |
200 | { "ok": true, "recorded": false, "duplicate": true, "release": {...} } | The same version was recorded in the last 10 minutes; release is that one |
404 | { "error": "not_found" } | The URL is wrong or was replaced, or the app is archived |
413 | { "error": "payload_too_large" } | The body is over 256 KB |
429 | { "error": "rate_limited" } | Too many requests. Try again shortly |
The release object has id, version, description, url, environment, source and at (Unix milliseconds).
Wait for the verdict
Every release gets a verdict: did it fail, and for whom? A CI step after deploy can ask for it with the same token and fail the build on a drop if you want a release gate. See wait for a release verdict in CI.