---
title: "Send deploys from CI"
section: "Deploys & Repos"
description: "Report deploys to SmartestQA from GitHub Actions, GitLab CI, Jenkins or any CI with one HTTP call: deploy token, webhook payload fields, statuses and token rotation."
url: https://docs.smartestqa.ai/en/deployments-ci.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "ci webhook deploy token sdt_ x-deploy-token github actions gitlab ci jenkins curl deploy notification payload environment commitSha status started success failure cancelled deployedAt regenerate token"
---
# Deploys & Repos: Send deploys from CI

Your CI tells SmartestQA when it deploys, with one HTTP request after the deploy step. This page covers the deploy token, the request, the ready-made CI steps and what happens to each notification.

## In short

**On this page you can**

- Copy the Webhook URL and the repository’s Deploy token .
- Paste a ready-made step for GitHub Actions, GitLab CI, Jenkins or plain curl.
- Send started and later success for the same commit; SmartestQA keeps one record.
- Replace a lost or leaked token with Generate new token .

**How to use it**

1. In Repositories , open the row menu › CI code & deploy token .
2. Store the token as a CI secret named SMARTEST_DEPLOY_TOKEN .
3. Copy the tab for your CI and add it after your deploy step.
4. Deploy once and check that the cell in Currently running versions shows the new commit.

## The deploy token

Each repository has its own deploy token. It starts with `sdt_` followed by 40 hexadecimal characters. It can only record deploys for that one repository: it gives no access to anything else in SmartestQA, and no SmartestQA login is needed to use it.

- SmartestQA stores only a fingerprint of the token, so it can show it **once**: when you create the repository and when you generate a new token.
- Afterwards the window shows “Token ending in …*abcd* is active. It is shown only once.” with the last four characters.
- Deleting the repository makes the token invalid.

## Add the CI step

1. **Open the CI window**

   In **Deploys & Repos** › **Repositories**, open the row’s ⋮ menu and choose **CI code & deploy token**. Right after you create a repository this window opens by itself, with the token visible.
2. **Store the token as a secret**

   Copy the **Deploy token** (copy icon; the tooltip changes to **Copied**). In your CI, add it as a secret, for example `SMARTEST_DEPLOY_TOKEN` in GitHub or GitLab, or a “Secret text” credential in Jenkins.
3. **Copy the step for your CI**

   Pick the tab: **GitHub Actions**, **GitLab CI**, **Jenkins**, **Shell script** or **curl**. The code already contains this server’s **Webhook URL** and the first environment of the repository’s mapping (TEST if none). Change the environment per job.
4. **Add it after the deploy**

   “Add this step after your deploy step. Store the token as a CI secret. A failed notification never breaks the deploy (|| true).” The ready-made steps run even when the deploy fails, so failed deploys are recorded too.
5. **Deploy and check**

   Run a deploy. The repository’s chip changes from [**No deploy received yet**](https://docs.smartestqa.ai/en/deployments-repos.html#connection-modes) to [**Webhook only**](https://docs.smartestqa.ai/en/deployments-repos.html#connection-modes) or [**Connected with token**](https://docs.smartestqa.ai/en/deployments-repos.html#connection-modes).

   The cell for that service and environment shows the short commit, the version and “just now”. Until a [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) runs there it shows **Not tested**.

### Example: GitHub Actions

Last step of the deploy job

```yaml
- name: Notify SmartestQA
  if: always()
  run: |
    curl -sS -X POST "https://<your-smartestqa-api>/api/deployments/webhook" \
      -H "Content-Type: application/json" \
      -H "X-Deploy-Token: ${{ secrets.SMARTEST_DEPLOY_TOKEN }}" \
      -d '{"environment":"TEST","commitSha":"${{ github.sha }}","version":"${{ github.ref_name }}","branch":"${{ github.ref_name }}","status":"${{ job.status }}","buildUrl":"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}","actor":"${{ github.actor }}"}' || true
```

Copy the real address from the **Webhook URL** box; it depends on your SmartestQA server. The **Shell script** tab calls a helper script, `smartest-notify-deploy.sh`, with the environment, status and version. If your team does not have that script, use the **curl** tab.

## The webhook request

Request

```http
POST /api/deployments/webhook
Content-Type: application/json
X-Deploy-Token: sdt_…

{"environment":"TEST","commitSha":"a1b2c3d4e5f6…","status":"success","version":"v2.14.0",
 "branch":"release/2.14","buildUrl":"https://ci.example.com/job/412","actor":"ayse",
 "deployedAt":"2026-11-06T18:59:00Z"}
```

Instead of `X-Deploy-Token` you can send `Authorization: Bearer sdt_…`.

| Field | Required | Rules |
| --- | --- | --- |
| `environment` | Yes | Upper-cased. Letters, digits, `-`, `_`, up to 32 characters. `PRODUCTION` is recorded as PRP,`DEVELOPMENT` as DEV, `STAGE` as STAGING. |
| `commitSha` | Yes | 7 to 64 hexadecimal characters. Send the full SHA. |
| `status` | No | `success`, `failure`, `cancelled` or `started`. Empty means success. See [Statuses](https://docs.smartestqa.ai/en/deployments-ci.html#statuses). |
| `version` | No | A tag or build number, up to 120 characters. Shown next to the commit. |
| `branch` | No | Up to 200 characters. `refs/heads/` and `refs/tags/` are removed. |
| `buildUrl` | No | The CI run, up to 1,000 characters. Only `http(s)` addresses are kept; they become the [**Open CI run**](https://docs.smartestqa.ai/en/deployments-overview.html#deploy-detail) link. |
| `actor` | No | Who deployed, up to 200 characters. Shown in the **By** column. |
| `description` | No | Free text, up to 1,000 characters. Shown as **Note** in the deploy detail. |
| `deployedAt` | No | ISO-8601 with time zone (`2026-11-06T18:59:00Z`) or Unix seconds or milliseconds. Empty means the moment the request arrives. |

Empty values never overwrite what a record already has, so a script can send `""` for fields it does not know.

### Statuses

| You send | Recorded as | Shown as |
| --- | --- | --- |
| `success`, `succeeded`, `successful`, `ok`, `deployed`, `passed`, `completed`, or nothing | SUCCEEDED | **Succeeded** |
| `failure`, `failed`, `error`, `errored` | FAILED | **Failed** |
| `cancelled`, `canceled`, `aborted`, `skipped` | CANCELLED | **Cancelled** |
| `started`, `start`, `in_progress`, `running`, `pending`, `queued` | STARTED | **In progress** |

Case does not matter. GitHub’s `job.status` values pass straight through. Anything else is refused with an error naming the four accepted values.

### Started, then success

If CI sends `started` and later `success` (or `failure`) for the same repository, environment and commit, SmartestQA updates the same record instead of adding a second one. The deploy time becomes the time of the final notification, so [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) runs count from the moment the deploy finished.

### What SmartestQA does with a successful deploy

1. Finds the previous successful deploy of the same repository in the same environment and stores its commit as the previous version.
2. If the commit is the same as before (a redeploy), records 0 commits and 0 files.
3. With an access token, reads the commits and changed files between the two versions.
4. Passes the deploy to [Autonomous Agents](https://docs.smartestqa.ai/en/ai-agents.html), so an agent that waits for deploys can start.
5. Updates the repository’s **Last deploy** time.

A failed, cancelled or in-progress deploy is recorded and shown, but it is not compared with the previous version and is not passed to agents.

### The response

Successful notification

```json
{"success": true, "code": 200,
 "data": {"deploymentId": 812, "repo": "web", "environment": "TEST", "commitSha": "a1b2c3d4e5f6…",
          "status": "SUCCEEDED", "previousSha": "9f8e7d6…", "updatedExisting": false}}
```

`updatedExisting` is `true` when the call completed a record that CI had opened with `started`. Errors return HTTP 401 (unknown token) or 400 (a field is missing or invalid), with the reason in `message`. See [Webhook errors](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#webhook).

## Generate a new token

Do this when the token is lost or may have leaked.

1. **Open the CI window**

   Row menu › **CI code & deploy token**. You see “Token ending in …*abcd* is active.”
2. **Generate**

   Click **Generate new token**. The warning reads “The current token stops working immediately; update your CI secret.” Click **Generate** (or **Cancel**).
3. **Update the CI secret**

   Copy the new token (“Copy it now — it will not be shown again.”) and replace the secret in every CI job of this repository.

   The next deploy is recorded with the new token. Jobs that still use the old one get HTTP 401, but their deploys are not affected.

> **Warning: Plan the switch**
>
> Between generating the token and updating CI, deploys are not recorded. Generate the token when no deploy is running, or send the missed deploy again afterwards with its `deployedAt`.

## If something goes wrong

- [The webhook answers 401](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-invalid-token)
- [The commit SHA is refused](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-bad-sha)
- [The status is refused](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-unknown-status)
- [CI ran but nothing appears](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-no-deploy-received)
