Deployment events and CI setup

CoRoid only marks a release deployed when your CI/CD says so. This page shows how a pipeline reports deployments, whether CoRoid starts it or it runs on its own.

Everything below is configured per environment in the project's Settings → Releases → Deploy pipeline. Create a reporting token there. An Owner or Admin sees it once. Store it as a secret in that environment's CI pipeline. CoRoid keeps only a hash, and replacing the token revokes the old one immediately. The token can report only for its project and environment. Never put it in a repository file or a browser request.

GitHub Actions and GitLab CI/CD#

If you want the Deploy to… button on the release page, choose CoRoid starts a GitHub Actions workflow or CoRoid starts a GitLab CI/CD pipeline in the environment's Deploy pipeline settings. Enter the exact deployment job name, the branch or tag ref, and the GitHub workflow filename when applicable. That ref must point to the release commit at request time, unless the GitHub workflow declares a coroid_artifact_sha input (see below). The GitHub workflow receives coroid_release_id, coroid_attempt_id, coroid_commit_sha, and coroid_environment inputs, plus coroid_version, coroid_build_number, coroid_release_name and coroid_artifact_sha when the workflow declares them. GitLab receives the equivalent uppercase COROID_* variables. Use these values to deploy and report the exact SHA and attempt.

A GitHub workflow that declares coroid_artifact_sha runs from its own ref, usually your default branch, and deploys the commit in that input. CoRoid can then deploy any release, including a rollback to an older one, with today's workflow, and the ref no longer has to point at the release commit. CoRoid records which commit the run started from and checks it when the run reports. The workflow should also record a GitHub deployment of the deployed commit whose status links the run, as CoRoid's deployment check reads it when the run started from another commit.

Two more optional inputs make deployments safe to recover:

• coroid_expected_revision is the commit the environment ran when the deployment was requested. Compare it with what the environment runs before you deploy. If they differ, someone deployed in between, so stop without deploying.
• coroid_rollback is true when the run rolls the environment back. Give such runs their own concurrency group, so a rollback never waits behind a deployment. Before a rollback, CoRoid cancels a deployment that is still running and waits until it has stopped. If it does not stop in time, nothing is rolled back and Owners and Admins are told.

GitLab receives them as COROID_EXPECTED_REVISION and COROID_ROLLBACK. Put the version in your build shows how to stamp the version into the build.

Name each run after its attempt, so CoRoid can find a run whose start it never heard back about. In GitHub Actions, set run-name to text that contains coroid_attempt_id. In GitLab, set workflow:name to text that contains $COROID_ATTEMPT_ID:

# GitHub Actions
run-name: ${{ inputs.coroid_attempt_id && format('Deploy (attempt {0})', inputs.coroid_attempt_id) || 'Deploy' }}

# GitLab CI/CD
workflow:
  name: 'Deploy $COROID_ATTEMPT_ID'

If CoRoid starts a run but the provider never confirms it started, the deployment waits. After 5 minutes CoRoid looks for a run with the attempt in its name and, if it finds one, follows that run. If no run is found after 15 minutes, the deployment ends as lost, its release is marked failed, and the environment accepts a new deployment.

Store the environment callback token in GitHub Actions secrets or GitLab CI/CD masked variables. Send a running event when the deployment job starts and a terminal succeeded, failed, or cancelled event when it finishes. CoRoid checks the provider run, commit, and named job before accepting success for a configured pipeline. The provider run URL remains the place to inspect logs.

A GitHub workflow that runs from one commit and deploys another, for example one with a ref input for deploying an older commit or rolling back, must say which commit it deployed. Create a GitHub deployment for the deployed commit in the environment, and give its final success status a log_url that links the workflow run. The GitHub App then needs the repository permission Deployments: Read-only. The CoRoid production workflow contains a concrete GitHub Actions example; adapt its secret names and job to your repository.

Generic CI callback#

An external pipeline can send the same events without enabling dispatch. Authenticate with the environment's scoped bearer token. The endpoint accepts JSON with this versioned shape:

POST /api/v1/release-deployment-events
Authorization: Bearer <environment-callback-token>
Content-Type: application/json

{
  "schemaVersion": 1,
  "eventId": "ci:run-812:production:succeeded",
  "providerRunId": "run-812",
  "projectId": "<project-uuid>",
  "environmentKey": "production",
  "repository": "owner/repository",
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "status": "succeeded",
  "occurredAt": "2026-09-24T12:00:00Z",
  "runUrl": "https://ci.example.com/runs/812"
}

Include releaseId and attemptId when reporting a run requested by CoRoid. Add version and buildNumber to record what you deployed. For a project hosted on CoRoid, repository is the project ID. failureReason can explain a failed run. Use queued, running, succeeded, failed, cancelled, or rolled_back for status. Report rolled_back when the run upgraded the environment, then restored the previous revision because the new one failed. Keep one providerRunId throughout a run and give each state transition a unique eventId. A retry of the same event should retain its ID; a new CI run needs a new run ID. A GitHub re-run keeps the attemptId and reports its run attempt in the providerRunId (<run id>-<run attempt>). If it re-runs the environment's latest deployment, CoRoid follows the same deployment. Otherwise CoRoid records it as a separate deployment it observed. The event timestamp must be recent. CoRoid checks repository, environment, commit, credential scope, and terminal state before applying it; conflicting events are held for review. A valid deployment without a prepared release can create an observed release, clearly separate from a preflight-approved candidate. It takes the version the event reports or, when CoRoid assigns the project's versions, the next one.

Version 2 of the event ("schemaVersion": 2) also reports the two identities of a deployment apart: what was deployed, and what deployed it. artifact holds the deployed commit, which must equal commitSha, and the digest of each image. workflow holds the commit the run started from, and optionally its ref:

{
  "schemaVersion": 2,
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "artifact": {
    "sha": "0123456789abcdef0123456789abcdef01234567",
    "images": [{ "name": "app", "digest": "sha256:…" }]
  },
  "workflow": {
    "sha": "89abcdef0123456789abcdef0123456789abcdef",
    "ref": "owner/repository/.github/workflows/deploy.yml@refs/heads/main"
  }
}

CoRoid holds a v2 event for review when its workflow commit is not the one the deployment was requested at, or when the provider shows the run starting from another commit. Version 1 events are still accepted.

For a pipeline without callbacks, an Owner or Admin can choose Record external deployment on the release page. Supply the environment, matching commit, time, and a reason or evidence URL. The resulting Manual attestation records the outcome without claiming that CoRoid ran CI or passed a gate.

Related#

• Release settings
• Releases
• Recovery and release trains
• Put the version in your build