배포 이벤트 및 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 워크플로에서 선언하는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 액션의 비밀값 또는 GitLab CI/CD의 마스킹된 변수에 저장하세요. 배포 작업이 시작될 때running이벤트를 전송하고, 종료 시에는 최종succeeded, failed, 또는cancelled실행이 완료되면 해당 이벤트가 발생합니다. CoRoid는 구성된 파이프라인의 성공 여부를 판단하기 전에 제공업체의 실행 정보, 커밋, 지정된 작업 내용을 확인합니다. 제공업체의 실행 URL에서 로그를 확인할 수 있습니다.

하나의 커밋에서 실행되어 다른 커밋을 배포하는 GitHub 워크플로의 경우, 예를 들어ref입력값을 사용해 이전 커밋을 배포하거나 롤백하는 경우, 어떤 커밋을 배포했는지 명시해야 합니다. 다음을 생성하세요.GitHub 배포환경에 배포된 커밋에 대해 설정하고, 최종success상태에log_url워크플로 실행 정보를 연결하는 항목을 지정하세요. 그러면 GitHub 앱에서배포: 읽기 전용권한이 필요합니다.CoRoid 프로덕션 워크플로우구체적인 GitHub 액션 예제가 포함되어 있으며, 비밀값 이름과 작업 내용은 사용 중인 저장소에 맞게 조정하세요.

일반 CI 콜백#

외부 파이프라인에서 디스패치를 활성화하지 않고도 동일한 이벤트를 전송할 수 있습니다. 환경에 한정된 베어러 토큰으로 인증하세요. 엔드포인트는 다음과 같은 버전별 형태의 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및attemptIdCoRoid가 요청한 실행을 보고할 때에는 다음을 추가하세요: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에는 실행이 시작된 커밋이 포함되며, 선택적으로 해당 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는 v2 이벤트를 검토용으로 보관합니다. 버전 1 이벤트도 여전히 허용됩니다.

콜백 기능이 없는 파이프라인의 경우 소유자나 관리자는외부 배포 기록하기릴리스 페이지에서 수행하세요. 환경, 일치하는 커밋, 시간, 그리고 사유 또는 증거 URL을 입력하세요. 결과로 생성되는 수동 인증서는 CoRoid가 CI를 실행했거나 게이트를 통과했다고 주장하지 않으면서도 결과를 기록합니다.

관련 항목#

• 릴리즈 설정
• 릴리스
• 복구 및 릴리즈 트레인
• 빌드에 버전을 포함시키세요