Releases

A release is a named point in time on a site, usually a deploy. With releases you can ask "did LCP go up after we shipped v2.4.1?" with one API call, instead of squinting at a chart.

Why it mattersCopy Anchor Link

Performance regressions almost always line up with a deploy. Without release markers, you've got to remember when each deploy happened and compare by hand. With markers, the Analytics API does the before/after comparison for you in a single request.

When you'd touch itCopy Anchor Link

• Every deploy. Cleanest setup: a POST /sites/{id}/releases from CI/CD after a successful deploy.
• Investigating a regression. On the LCP or TTFB page, Compare → Release, against the one before shows a release next to the previous one.
• Rolling back. Tag the rollback as a release too; you want both transitions visible.

If you don't tag releases, nothing breaks. The dashboard still works without them. You just lose the deploy-correlation shortcut.

What's on a releaseCopy Anchor Link

That's the whole resource. Releases are minimal on purpose; the goal is correlation, not building a deploy database.

Tagging from CI/CDCopy Anchor Link

The reliable way is a step at the end of your deploy job:

curl https://api.fastmon.eu/sites/$FASTMON_SITE_ID/releases \
  -H "Authorization: Bearer fm_$FASTMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"version\": \"$DEPLOY_VERSION\", \"released_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" }"

Use whatever your CI considers a deploy version: git SHA, tag, build number. Whatever you pick, stick with it. Mixing styles makes the sort order meaningless.

VercelCopy Anchor Link

Add a deploy hook command. The VERCEL_GIT_COMMIT_SHA env var is populated automatically.

GitHub ActionsCopy Anchor Link

A final step in the deploy job, with ${{ github.sha }} or ${{ github.ref_name }} as the version.

GitLab CICopy Anchor Link

A release stage after the deploy stage, using $CI_COMMIT_SHA or $CI_COMMIT_TAG.

Comparing releasesCopy Anchor Link

Send a release's window as time_range and the previous release as compare_to: { "release_id": … }. Each row of the result then carries a comparison with the same metrics. The steps and an example are in Compare releases.

Common scenariosCopy Anchor Link

Continuous deploysCopy Anchor Link

Tag every deploy, volume is no problem. The Compare picker lists the releases of the last 90 days, newest first, and older ones stay queryable by ID.

Long-running release branchesCopy Anchor Link

Tag at the moment the new version actually reaches meaningful traffic: when you flip the feature flag, swap the canary, or move the load balancer. Don't tag on "deploy finished, nobody saw it yet."

RollbacksCopy Anchor Link

Tag the rollback as a separate release with a version like rollback-v2.4.0. The dashboard should show all three transitions: buggy release goes live, regression hits, rollback brings metrics back to baseline.

Common surprisesCopy Anchor Link

• released_at matters more than id. Sorting is by released_at. Back-date a release and the order will look wrong.
• Releases are per site. A monorepo shipping several sites needs one release call per site, even if the version string is identical.
• Deleting a release breaks comparisons that reference it. The endpoint returns 404. Metrics already rendered aren't affected.

RelatedCopy Anchor Link

• Sites: releases live under a site.
• Analytics API: compare_to.
• Compare releases: step-by-step guide for hooking up CI/CD.