- Docs
- Resources
- Deploys & Repos
- Send deploys from CI
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
startedand latersuccessfor the same commit; SmartestQA keeps one record. - Replace a lost or leaked token with Generate new token.
How to use it
- In Repositories, open the row menu › CI code & deploy token.
- Store the token as a CI secret named
SMARTEST_DEPLOY_TOKEN. - Copy the tab for your CI and add it after your deploy step.
- 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#
Open the CI window
In Deploys & ReposRepositories, 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.
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_TOKENin GitHub or GitLab, or a “Secret text” credential in Jenkins.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.
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.
Deploy and check
Run a deploy. The repository’s chip changes from No deploy received yet to Webhook only or Connected with token.
The cell for that service and environment shows the short commit, the version and “just now”. Until a pipeline runs there it shows Not tested.
Example: GitHub Actions#
- 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 }}"}' || trueCopy 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#
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. |
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 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 runs count from the moment the deploy finished.
What SmartestQA does with a successful deploy#
- Finds the previous successful deploy of the same repository in the same environment and stores its commit as the previous version.
- If the commit is the same as before (a redeploy), records 0 commits and 0 files.
- With an access token, reads the commits and changed files between the two versions.
- Passes the deploy to Autonomous Agents, so an agent that waits for deploys can start.
- 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#
{"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.
Generate a new token#
Do this when the token is lost or may have leaked.
Open the CI window
Row menu › CI code & deploy token. You see “Token ending in …abcd is active.”
Generate
Click Generate new token. The warning reads “The current token stops working immediately; update your CI secret.” Click Generate (or Cancel).
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.
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#
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai