部署事件与CI集成配置

CoRoid 仅在你的 CI/CD 确认后才会标记版本已部署。本页展示了流水线如何上报部署情况，无论是由 CoRoid 发起还是自行运行。

以下内容均需在项目的对应环境中进行配置：设置 → 版本发布 → 部署流水线在此处创建一个上报令牌。所有者或管理员仅能查看一次该令牌。将其作为机密信息存储在该环境的 CI 流水线中。CoRoid 仅保留其哈希值，替换令牌后会立即吊销旧令牌。该令牌仅能为其所属的项目和环境上报数据。切勿将其放入仓库文件或浏览器请求中。

GitHub 操作与 GitLab CI/CD#

如果你希望部署到…在版本发布页面上点击该按钮，选择CoRoid 会启动一个 GitHub Actions 工作流或CoRoid 会启动一个 GitLab CI/CD 流水线在环境的部署流水线设置中进行配置。输入准确的部署任务名称、分支或标签引用，以及适用的 GitHub 工作流文件名。该引用在请求时必须指向发布提交，除非 GitHub 工作流声明了coroid_artifact_sha输入参数（见下文）。GitHub 工作流会接收coroid_release_id、coroid_attempt_id、coroid_commit_sha以及coroid_environment输入参数，此外还有coroid_version、coroid_build_number、coroid_release_name和coroid_artifact_sha当工作流声明了这些参数时。GitLab 会收到对应的大写COROID_*变量。利用这些值即可部署并上报准确的 SHA 值和尝试次数。

一个声明了 GitHub 的 GitHub 工作流coroid_artifact_sha该流水线从其自身的引用开始运行，通常为默认分支，并部署该引用中的提交。随后 CoRoid 可部署任意版本，包括回滚到旧版本，且无需引用指向版本提交。CoRoid 会记录运行起始的提交，并在运行上报时校验该提交。工作流还应记录所部署提交的 GitHub 部署信息，其状态会关联该运行，因为若运行起始于其他提交，CoRoid 的部署校验会读取该信息。

另外两个可选输入可让部署安全恢复：

• coroid_expected_revision是请求部署时环境正在运行的提交。 部署前请将其与环境当前运行的提交进行比较。如果两者不同，说明期间有人进行了部署，因此应停止，不要 执行部署。
• coroid_rollback是true当运行需要回滚环境时，为这类运行分配独立的并发组，确保回滚不会因部署任务而延迟。回滚前，CoRoid 会取消仍在运行的部署任务，并等待其停止。若未及时停止，则无法完成回滚，系统会通知所有者和管理员。

GitLab 会将它们作为COROID_EXPECTED_REVISION和COROID_ROLLBACK。在构建中写入版本号介绍如何将版本号写入 构建产物。

根据尝试次数命名每个运行，以便 CoRoid 能找到未收到反馈的运行。在 GitHub Actions 中，设置run-name设置为包含coroid_attempt_id。在 GitLab 中，将workflow:name设置为包含$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'

若 CoRoid 启动了运行但提供商未确认其已启动，部署任务将处于等待状态。5分钟后，CoRoid 会查找名称中包含对应尝试次数的运行，找到则跟随该运行。若15分钟后仍未找到对应运行，部署将被标记为丢失，其版本会标记为失败，环境可接受新的部署。

将环境回调令牌存储在 GitHub Actions 密钥或 GitLab CI/CD 掩码变量中。部署作业开始时发送一个running事件，结束时发送一个终态succeeded、failed或cancelled运行结束时触发该事件。CoRoid 会在接受配置好的流水线的成功状态前，校验提供商运行、提交和指定任务。提供商运行 URL 仍是查看日志的位置。

一个从某个提交运行、却部署了另一个提交的 GitHub 工作流，例如 使用ref输入来部署较早的提交或执行回滚的工作流，必须 说明实际部署的是哪个提交。请在环境中为已部署的提交创建一个GitHub 部署，并为其最终success状态提供一个log_url，以关联工作流运行。随后，GitHub App 需要拥有该代码库的Deployments: Read-only。CoRoid 生产工作流包含一个具体的 GitHub Actions 示例；请根据你的代码库调整密钥名称和作业。

通用 CI 回调#

外部流水线无需启用 dispatch，也可以发送相同事件。 使用环境范围限定的 bearer 令牌进行身份验证。此端点接受 具有以下版本化结构的 JSON：

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"
}

包含releaseId和attemptId上报由 CoRoid 请求的运行信息时，添加version和buildNumber以记录你部署的内容。对于托管在 CoRoid 上的项目，repository是项目 ID。failureReason可以解释运行失败的原因。使用queued、running、succeeded、failed、cancelled，或rolled_back用于status。报告rolled_back当运行过程升级了环境后，因新版本存在故障而恢复了先前的修订版。请保留一个providerRunId在整个运行过程中使用，并为每个状态转换赋予唯一的eventId。同一事件的重试应保留其ID；新的CI运行需要新的运行ID。GitHub的重试会保留attemptId并会在报告中标注其运行尝试次数providerRunId (<run id>-<run attempt>）。若它重新运行环境的最新部署，CoRoid 会遵循相同的部署流程；否则 CoRoid 会将其记录为单独观测到的部署。事件时间戳必须较新。CoRoid 在应用该部署前会校验仓库、环境、提交、凭证范围和终端状态；冲突事件会被搁置以待审核。没有预备版本的合法部署可生成观测到的版本，该版本与预检批准的候选版本有明显区别。它会采用version事件上报的内容，或当 CoRoid 为项目分配版本时，采用下一个版本。

事件的版本2（"schemaVersion": 2)还会分别报告部署的两个标识：被部署的内容以及执行部署的主体。artifact保存被部署的提交内容，该内容必须与commitSha一致，同时保存每个镜像的摘要。workflow保存运行起始所用的提交内容，可选附带其引用：

{
  "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 会保留 v2 事件待审核。版本 1 事件仍可被接受。

对于没有回调机制的流水线，所有者或管理员可选择记录外部部署在版本页面操作。填写环境、匹配的提交、时间以及原因或证据 URL。生成的手动 attestation 会记录结果，但不会声称 CoRoid 运行了 CI 或通过相关校验。

相关#

• 发布设置
• 版本发布
• 恢复与发布流水线
• 将版本号嵌入构建流程