- Create a write tokenGo to Settings, open API tokens, tick Write, set an expiry and choose "Create token". Store it as a CI secret.
- Copy your workspace idGo to Settings, Workspace and copy the Workspace id.
- Post a marker after deploysAdd a step to your pipeline that POSTs service and version to the deployments API, or run monctl deploy.
- Target monitors (optional)Add monitor_ids, tags or project_id so the marker applies to the right monitors.
- Check the listOpen Settings, Deployments to see recorded markers.
A deployment marker records what was deployed, where and when. When an incident opens within an hour after a marker for the same monitors, the incident page lists that deploy under Recent deployments as possibly related: a hint to check first, never a proven cause. A marker can also open a short maintenance window so expected restarts do not page anyone. Deployment markers need Starter or Team.
Before you start
- A workspace on Starter or Team.
- An API token with the Write scope. Owners and admins create tokens under Settings → API tokens; the token acts with its creator's permissions, so its creator must be allowed to edit the affected monitors.
- Your Workspace id, shown under Settings → Workspace.
Send a marker from CI
After a successful deploy, POST to the deployments endpoint:
curl -fsS -X POST "https://uptimetracker.live/api/v1/workspaces/$MONITORING_WORKSPACE/deployments" \
-H "Authorization: Bearer $MONITORING_TOKEN" -H "Content-Type: application/json" \
-d '{"service":"checkout","version":"v2.4.1","environment":"production","source":"github","tags":["checkout"],"maintenance_minutes":10}'Or with the CLI: monctl deploy --service checkout --version v2.4.1 --env production --tag checkout --maintenance 10. A full GitHub Actions example is in API tokens, the REST API and the monctl CLI.
Fields
| Field | Required | Notes |
|---|---|---|
service | Yes | Up to 120 characters |
version | Yes | Up to 200 characters, such as a tag or commit SHA |
environment | No | Default production, up to 60 characters |
source | No | github, gitlab, jenkins, cli, api (default) or other |
url | No | An http(s) link to the CI run or release |
description | No | Up to 1,000 characters |
monitor_ids, tags, project_id | No | Which monitors the deploy affects. None means the whole workspace. |
maintenance_minutes | No | 1 to 30: opens a maintenance window for the targeted monitors |
Deploy maintenance windows
With maintenance_minutes, a maintenance window starts at the deploy time for every targeted monitor (listed ids, any monitor with one of the tags, or the project's monitors) and holds alerts while it lasts. A marker without targets is recorded workspace-wide but opens no window. If a monitor is still down when the window ends, alerts go out as usual.
Without a CI step: deploy hooks
GitHub, GitLab, Vercel and Netlify can send signed webhooks that record markers for you. See deploy hooks.
See your markers
Settings → Deployments lists recent markers with service, version (linked to the run when a url was sent), environment, the monitors it affects, the maintenance window and the source. On an incident, deploys from the hour before it opened appear under Recent deployments.
Troubleshooting
- HTTP 402, "deployment markers are available on Starter and higher": the workspace is on Free.
- HTTP 403: the token is read-only, or its creator cannot edit the targeted monitors or project.
- "Every monitor must belong to this workspace": a monitor id is from another workspace or was deleted.
- The deploy is not shown on the incident: it was more than an hour before the incident opened, or it targeted other monitors.
Frequently asked questions
Which plan includes deployment markers?
Starter and Team.
Does a marker mean the deploy caused the incident?
No. Deploys in the hour before an incident are shown as possibly related, a hint to check rather than a proven cause.
How long can a deploy maintenance window be?
Between 1 and 30 minutes, set with maintenance_minutes.
