Mark releases
Last updated
When conversions drop, the first question is what changed. Releases answer it. Each release you record shows on the Overview chart, starts a fresh result for every protected flow, and is named in alerts that follow it.
There are three ways releases get recorded: a deploy hook called from your CI or hosting, new app versions seen in your events, and releases you add by hand. You manage all three on the app's Integrations page, under Releases.
Where releases show
- Overview chart. Each release is a marker on the chart. Under the chart, a line such as "2 releases in this period" lists the versions. Select Show to see each release's time, source, description and a Release notes link, if it has one.
- Protected flows. Each protected flow is judged on everything since the app's latest release. See how verdicts use releases.
- Alerts. Alerts name the release they likely follow. See alerts.
Set up the deploy hook
The deploy hook is a private URL for your app. Anything that posts to it after a production deploy records a release.
To set it up:
- Open your app and select Integrations.
- Under Releases, select Set up deploy hook.
- Copy the URL and the example, and store the URL in your CI secrets. Anyone with the URL can add releases to this app.
Showing the hook URL needs the "See and rotate write keys and hook URLs" permission. Once it's set up, the Releases row shows when the hook was last used.
From any CI pipeline
Add a step after your production deploy that posts the version as JSON:
curl -X POST "$METRICKLE_DEPLOY_HOOK" \
-H "content-type: application/json" \
-d '{"version": "1.4.0", "description": "Checkout fixes", "url": "https://github.com/acme/web/releases/v1.4.0"}'
Only version is required. description and url show in the release list, and url becomes the Release notes link. Call it from production deploys only: every release you post starts a new result for your protected flows.
From GitHub, Vercel or Netlify
You can point a webhook at the same URL without changing anything:
| Service | Where to add it | What records a release |
|---|---|---|
| GitHub | Settings, Webhooks, content type application/json | Published releases (not drafts or pre-releases), and successful deployment statuses |
| Vercel | Settings, Webhooks | Deployment Succeeded, production deploys only |
| Netlify | Site configuration, Notifications, Outgoing webhook | Deploy succeeded |
Pings, failed deploys and preview, staging or branch deploys are ignored. For a commit, the version is the short commit hash.
Replace the URL
If the URL leaks, select Deploy hook, then Replace URL. The old URL stops working straight away, so update it everywhere you've set it up.
App versions from your events
If your events carry an app version, each new version is added as a release automatically, dated when it was first seen. Metrickle checks every hour. The versions already live when it first looks at your app aren't added, so you don't get a burst of old releases.
The iOS and Android SDKs send your app's version on their own. On Flutter, React Native and the web, set appVersion when you start the SDK. See the install guide.
The Versions tab on the Overview's Technology card shows how many visitors are on each version.
Add or remove a release by hand
To add one:
- On Integrations, under Releases, select Add release.
- Enter the Version, and a Description if you want one.
- Select Add release. It's marked now on the Overview chart.
To remove one, select View all to open Releases, last 90 days, then the remove button next to the release. Adding and removing releases needs the "Add and remove releases" permission. AI assistants connected through Connect AI can list releases, and add one after a deploy when their token has that permission. See AI assistants over MCP.
The list labels each release by where it came from: Deploy hook, Added by hand or New app version.
How verdicts use releases
Each protected flow is judged on everything since the app's latest release, so the result is about what's live now. The result card says which, for example "Since release 1.4.0".
- Right after a release, a flow often reads Needs more usage or shows groups with Too few attempts, until enough people have tried it.
- If there's been no release in the last 14 days, the result covers the last 7 days instead.
- Any release counts, whichever way it was recorded. A stray release resets the window, so remove one that wasn't a real production deploy.
Alerts
When a protected flow changes to Gap found, the alert includes Since release with the version and who added it, if a person did.
Alerts for a drop in task success and for new friction hotspots include Latest release when one went out in the two days before, with how many hours ago. Set up where alerts go on the Integrations page. See integrations.