# Deploy markers

> One call at the end of your deploy job, and Clerion sets each deploy's error rate and conversion against the day before. GitHub Actions and any CI.

To mark a deploy in Clerion, add one HTTP call to the end of your deploy job: a POST to `https://api.getclerion.com/api/v1/deploys` with your Clerion key and your site id. The Errors page then shows each deploy with its error rate and conversion rate for the 24 hours before against the 24 hours after, and the briefing can name the deploy behind a change.

[Clerion's Deploys card: the cursor goes to New delivery step, then across to its error rate rising from 1% to 6.2% and conversion falling from 3.4% to 2.1%](/product/clips/deploys.mp4 "clip")

## Before you start

You need two things from the dashboard:

| What | Where to find it |
|---|---|
| Your key | Your model, in the sidebar. It starts with `clm_` and is the same key Claude and Cursor use. Available on Growth, Business and during the trial. |
| Your site id | The `data-website-id` value in your snippet, or the part of the dashboard address that starts with `site_`. |

Store the key as a secret in your CI, never in the repository. Anyone holding it can read your analytics through the MCP server.

## Send the call

From any shell or CI step:

```bash
curl -X POST https://api.getclerion.com/api/v1/deploys \
  -H "Authorization: Bearer $CLERION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"websiteId":"site_...","label":"v1.8"}'
```

The body takes three fields:

| Field | Required | What it does |
|---|---|---|
| `websiteId` | Yes | The site the deploy belongs to. |
| `label` | No | What shipped, up to 80 characters: a version, a branch, a commit. Shown in the dashboard and named by the briefing. |
| `deployedAt` | No | An ISO time within the last week, if the call is sent after the fact. Defaults to now. |

A successful call returns `200` with the deploy as recorded.

### GitHub Actions

Add the key as a repository secret called `CLERION_KEY`, then add a last step to the job that deploys:

```yaml
- name: Mark the deploy in Clerion
  if: success()
  run: |
    curl -fsS -X POST https://api.getclerion.com/api/v1/deploys \
      -H "Authorization: Bearer ${{ secrets.CLERION_KEY }}" \
      -H "Content-Type: application/json" \
      -d "{\"websiteId\":\"site_...\",\"label\":\"${GITHUB_REF_NAME} ${GITHUB_SHA::7}\"}"
```

`if: success()` keeps a failed deploy from being marked. `-f` makes the step fail loudly if the key is wrong, so you notice.

### GitLab CI

```yaml
deploy:
  script:
    - ./deploy.sh
    - >
      curl -fsS -X POST https://api.getclerion.com/api/v1/deploys
      -H "Authorization: Bearer $CLERION_KEY"
      -H "Content-Type: application/json"
      -d "{\"websiteId\":\"site_...\",\"label\":\"$CI_COMMIT_REF_NAME $CI_COMMIT_SHORT_SHA\"}"
```

Add `CLERION_KEY` as a masked CI variable.

### A deploy script, marking the real time

If your deploy finishes a while after the command runs, record the time it went live:

```bash
#!/bin/sh
set -e
./release.sh
AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -fsS -X POST https://api.getclerion.com/api/v1/deploys \
  -H "Authorization: Bearer $CLERION_KEY" -H "Content-Type: application/json" \
  -d "{\"websiteId\":\"site_...\",\"label\":\"$(git rev-parse --short HEAD)\",\"deployedAt\":\"$AT\"}"
```

### From Node

```js
await fetch("https://api.getclerion.com/api/v1/deploys", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CLERION_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ websiteId: "site_...", label: process.env.RELEASE_TAG }),
});
```

### Other CI and hosts

Any system that can run a command after a deploy can send the same `curl`: GitLab CI, CircleCI, Bitbucket Pipelines, or a deploy script on your own server. Put it after the step that makes the new version live, not after the build, so the time marks when visitors started getting it.

## Read the Deploys card

Open your site, go to Observability, then Errors, and scroll below the event log. Each deploy in the selected period has one row:

| Column | What it means |
|---|---|
| Deploy | Your label and the time it was recorded. |
| Sessions | Visits in the 24 hours before, then the 24 hours after. |
| Error rate | The share of those visits that hit at least one JavaScript error, before and after, with the change in points. |
| Conversion | The share of visits that sent any custom event, before and after, with the change in points. |

A change for the worse is marked in red. A deploy less than six hours old shows as still settling and is not judged, because a few hours of traffic are too few to read.

The briefing and Ask Clerion see the same rows. When a drop starts on the day of a deploy and that deploy moved errors or conversion, the briefing names it.

## Limits

| Limit | What it means for you |
|---|---|
| A paid plan | The key exists on Growth, Business and the trial. On Starter there is no key to send. |
| 24 hours each side | Two deploys on the same day share some of those hours, so their numbers overlap. |
| Conversion means any custom event | It is the share of visits that sent one, not one goal in particular. |
| 50 deploys per range | The card lists up to 50 deploys in the selected period. |
| Very busy sites | The card reads up to 150,000 events per site for the range. Above that it says so, and a shorter range can bring it back. |

## If the call fails

| Response | Cause |
|---|---|
| `401` | The key is missing, mistyped, or was replaced in Your model. Copy the current one. Replacing the key stops the old one everywhere at once. |
| `404` | The site id is not a site on the account that owns the key. |
| `400` | `websiteId` is missing, or `deployedAt` is more than a week away from now. |

## Questions

### Does marking a deploy change my analytics?

No. It adds a row to the Deploys card and a fact for the briefing. Visits, events and errors are counted exactly as before.

### Can I mark a deploy by hand?

Yes. The same `curl` from a terminal works; give it a label such as `pricing page copy`.

### Is the key safe to put in CI?

As a CI secret, yes. It reads analytics and records deploys, and cannot change or delete anything else. If it leaks, replace it in Your model and every copy stops working.

### Which deploys should I mark?

Production only. Preview and staging deploys get no real traffic, so their before and after would be empty.

---

Source: https://getclerion.com/docs/deploy-markers (Clerion docs, Releases). The whole manual as one file: https://getclerion.com/docs/everything.md