Eventos de implantação e configuração de CI

CoRoid só marca um release como implantado quando o seu CI/CD assim o indicar. Esta página mostra como um pipeline relata implantações, seja quando CoRoid as inicia ou quando elas são executadas de forma independente.

Tudo abaixo é configurado por ambiente nas Configurações do projeto. Configurações → Lançamentos → Pipeline de implantaçãoCrie um token de relatório ali. Um Proprietário ou Administrador o visualiza uma única vez. Armazene-o como um segredo no pipeline de CI desse ambiente. CoRoid retém apenas um hash, e a substituição do token revoga imediatamente o antigo. O token só pode gerar relatórios para seu projeto e ambiente. Nunca o coloque em um arquivo de repositório ou em uma requisição de navegador.

Ações do GitHub e GitLab CI/CD#

Se você quiser o Implantar em… botão na página de lançamentos, escolha CoRoid inicia um fluxo de trabalho do GitHub Actions ou CoRoid inicia um pipeline do GitLab CI/CD nas configurações do pipeline de implantação do ambiente. Insira o nome exato da tarefa de implantação, a referência de branch ou tag e o nome do arquivo de fluxo de trabalho do GitHub quando aplicável. Essa referência deve apontar para o commit de lançamento no momento da solicitação, a menos que o fluxo de trabalho do GitHub declare um coroid_artifact_sha entrada (veja abaixo). O fluxo de trabalho do GitHub recebe coroid_release_id, coroid_attempt_id, coroid_commit_sha, e coroid_environment entradas, além de coroid_version, coroid_build_number, coroid_release_name e coroid_artifact_sha quando o fluxo de trabalho os declara. GitLab recebe as variáveis equivalentes em maiúsculas COROID_* Use esses valores para implantar e relatar o SHA e a tentativa exatos.

Um fluxo de trabalho do GitHub que declara coroid_artifact_sha Ele é executado a partir de sua própria referência, geralmente seu branch padrão, e implanta o commit contido nesse input. CoRoid pode então implantar qualquer release, incluindo um rollback para um mais antigo, usando o fluxo de trabalho atual, e a referência não precisa mais apontar para o commit do release. CoRoid registra de qual commit a execução teve início e o verifica quando o fluxo de trabalho gera o relatório. O fluxo de trabalho também deve registrar uma implantação do GitHub do commit implantado, cujo status vincula a execução, já que a verificação de implantação do CoRoid lê essas informações quando a execução começou a partir de outro commit.

Mais duas entradas opcionais tornam as implantações seguras para recuperação:

• coroid_expected_revision é o commit que o ambiente executava quando a implantação foi solicitada. Compare-o com o que o ambiente executa antes de implantar. Se forem diferentes, alguém implantou entre os processos, então pare sem realizar a implantação.
• coroid_rollback é true Isso ocorre quando a execução faz o rollback do ambiente. Atribua a essas execuções seu próprio grupo de concorrência, para que um rollback nunca aguarde atrás de uma implantação. Antes de um rollback, CoRoid cancela uma implantação ainda em andamento e aguarda até que ela seja interrompida. Se ela não parar a tempo, nada será revertido e os Proprietários e Administradores serão notificados.

GitLab os recebe como COROID_EXPECTED_REVISION e COROID_ROLLBACK. Coloque a versão na sua compilação mostra como gravar a versão na compilação.

Nomeie cada execução conforme sua tentativa, para que CoRoid possa encontrar uma execução da qual não recebeu confirmação de início. No GitHub Actions, defina run-name para um texto que contenha coroid_attempt_idNo GitLab, defina workflow:name para um texto que contenha $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'

Se CoRoid inicia uma execução, mas o provedor nunca confirma seu início, a implantação aguarda. Após 5 minutos, CoRoid procura por uma execução cujo nome contenha a tentativa e, se a encontrar, segue essa execução. Se nenhuma execução for encontrada após 15 minutos, a implantação é considerada perdida, seu release é marcado como com falha e o ambiente aceita uma nova implantação.

Armazene o token de callback do ambiente nos segredos do GitHub Actions ou nas variáveis mascaradas do GitLab CI/CD. Envie um evento running quando a tarefa de implantação começar e um evento terminal succeeded, failed, ou cancelled evento ao finalizar. CoRoid verifica a execução do provedor, o commit e a tarefa nomeada antes de aceitar o sucesso para um pipeline configurado. A URL da execução do provedor continua sendo o local para inspecionar os logs.

Um fluxo de trabalho do GitHub que roda a partir de um commit e implanta outro, por exemplo um com uma ref entrada para implantar um commit mais antigo ou fazer rollback, deve informar qual commit foi implantado. Crie um Implantação do GitHub para o commit implantado no ambiente e dê ao seu status final success um log_url que vincula a execução do fluxo de trabalho. O aplicativo GitHub então precisa da permissão de repositório Implantações: Somente leituraO Fluxo de trabalho de produção do CoRoid contém um exemplo concreto do GitHub Actions; adapte seus nomes de segredos e tarefas ao seu repositório.

Callback genérico de CI#

Um pipeline externo pode enviar os mesmos eventos sem habilitar o despacho. Autentique-se com o token bearer escopo do ambiente. O endpoint aceita JSON com esta estrutura versionada:

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

Inclua releaseId e attemptId ao relatar uma execução solicitada pelo CoRoid. Adicione version e buildNumber para registrar o que foi implantado. Para um projeto hospedado no CoRoid, repository é o ID do projeto. failureReason pode explicar uma execução falha. Use queued, running, succeeded, failed, cancelled, ou rolled_back para status. Relatório rolled_back quando a execução atualizou o ambiente e depois restaurou a revisão anterior porque a nova versão falhou. Mantenha um providerRunId durante toda uma execução e atribua um identificador único para cada transição de estado eventId. Uma nova tentativa do mesmo evento deve manter seu ID; uma nova execução de CI precisa de um novo ID de execução. Uma nova execução do GitHub mantém o attemptId e registra sua tentativa de execução no providerRunId (<run id>-<run attempt>). Se ele reexecutar a implantação mais recente do ambiente, CoRoid seguirá a mesma implantação. Caso contrário, CoRoid a registrará como uma implantação separada que observou. O carimbo de data/hora do evento deve ser recente. CoRoid verifica o repositório, o ambiente, o commit, o escopo das credenciais e o estado final antes de aplicá-lo; eventos conflitantes são mantidos para revisão. Uma implantação válida sem um release preparado pode criar um release observado, claramente separado de um candidato aprovado em pré-verificação. Ele utiliza o version que o evento relata ou, quando CoRoid atribui as versões do projeto, a próxima versão.

Versão 2 do evento ("schemaVersion": 2) também registra as duas identidades de uma implantação: o que foi implantado e o que realizou a implantação. artifact contém o commit implantado, que deve ser igual a commitSha, e o digest de cada imagem. workflow contém o commit a partir do qual a execução começou e, opcionalmente, sua referência:

{
  "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 mantém um evento v2 para revisão quando o commit do fluxo de trabalho não é aquele solicitado para a implantação, ou quando o provedor indica que a execução começou a partir de outro commit. Eventos de versão 1 ainda são aceitos.

Para um pipeline sem retornos de chamada, um Proprietário ou Administrador pode escolher Registrar implantação externa na página do release. Informe o ambiente, o commit correspondente, o horário e um motivo ou URL de evidência. A certificação manual resultante registra o resultado sem afirmar que CoRoid executou CI ou passou por uma etapa de validação.

Relacionado#

• Configurações de versão
• Lançamentos
• Recuperação e linhas de versão
• Inclua a versão na sua compilação