Criar regras de proteção de implantação personalizadas

Use o GitHub Apps para automatizar a proteção de implantações com sistemas de terceiros.

Quem pode usar esse recurso?

As regras de proteção de implantação personalizadas estão disponíveis em repositórios públicos para todos os planos. Para acessar as regras de proteção de implantação personalizadas em repositórios privados ou internos, você deve usar GitHub Enterprise. Para mais informações, confira "Planos do GitHub".

Neste artigo

Nota: regras de proteção de implementação personalizada estão atualmente em versão prévia pública e sujeitas a alterações.

Sobre regras de proteção de implantação personalizada

Você pode habilitar suas próprias regras de proteção personalizadas para bloquear implantações com serviços de terceiros. Por exemplo, você pode usar serviços como Datadog, Honeycomb e ServiceNow para fornecer aprovações automatizadas para implantações no GitHub.

As regras de proteção de implantação personalizadas são alimentadas pelo GitHub Apps e executadas com base em webhooks e retornos de chamada. A aprovação ou rejeição de um trabalho de fluxo de trabalho baseia-se no consumo do webhook deployment_protection_rule. Para obter mais informações, confira "Eventos e cargas de webhook" e "Aprovação ou rejeição de implantações".

Depois de criar uma regra de proteção de implementação personalizada e instalá-la em seu repositório, a regra de proteção de implementação personalizada estará automaticamente disponível para todos os ambientes no repositório.

Usar regras de proteção de implantação personalizadas para aprovar ou rejeitar implantações

As implantações em um ambiente podem ser aprovadas ou rejeitadas com base nas condições definidas em qualquer serviço externo, como um tíquete aprovado em um sistema ITSM (gerenciamento de serviços de TI), resultado de verificação vulnerável em dependências ou métricas de integridade estáveis de um recurso de nuvem. A decisão de aprovar ou rejeitar implantações fica a critério do aplicativo integrador de terceiros e das condições de gating que você define neles. Confira a seguir alguns casos de uso para os quais você pode criar uma regra de proteção de implantação.

  • ITSM & Operações de Segurança: você pode verificar a prontidão do serviço validando processos de qualidade, segurança e conformidade que verificam a prontidão da implantação.
  • Sistemas de observabilidade: você pode consultar sistemas de monitoramento ou observabilidade (Sistemas de gerenciamento de desempenho de ativos e agregadores de registro, sistemas de verificação de integridade de recursos em nuvem, etc.) para verificar a prontidão de segurança e implantação.
  • Ferramentas de teste e qualidade de código: você pode verificar testes automatizados em compilações de CI que precisam ser implantados em um ambiente.

Como alternativa, você pode escrever suas próprias regras de proteção para qualquer um dos casos de uso acima ou pode definir qualquer lógica personalizada para aprovar ou rejeitar implantações com segurança desde a pré-produção até os ambientes de produção.

Criar uma regra de proteção de implantação personalizada com o GitHub Apps

  1. Crie um GitHub App. Para obter mais informações, confira "Registrar um Aplicativo GitHub". Configure o GitHub App da seguinte maneira.

    1. Opcionalmente, no campo de texto URL de Retorno de Chamada em "Identificar e autorizar usuários", insira a URL de retorno de chamada. Para obter mais informações, confira "Sobre a URL de retorno de chamada de autorização do usuário".
    2. Em "Permissões", selecione Permissões de repositório.
    3. À direita de "Ações", clique no menu suspenso e selecione Acesso: somente leitura.
      Captura de tela da seção "Permissões do repositório" durante a criação de um aplicativo GitHub. O botão para configurar permissões, com a permissão "somente leitura" selecionada, para Ações é realçado por um retângulo laranja escuro.
    4. À direita de "Implantações", clique no menu suspenso e selecione Acesso: Leitura e gravação.
      Captura de tela das configurações de permissão "Implantações" na seção "Permissões do repositório" durante a criação de um aplicativo GitHub. O botão para configurar permissões, com a permissão "somente leitura" selecionada, para Implantações é realçado por um retângulo laranja escuro.
    5. Em "Assinar eventos", selecione Regra de proteção de implantação.
      Captura de tela da seção "Assinar eventos" durante a criação de um aplicativo GitHub. A caixa de seleção para assinar o evento de regra de proteção de implantação é realçada por um retângulo laranja escuro.

  2. Instale a regra de proteção de implantação personalizada em seus repositórios e habilite-a para uso. Para obter mais informações, confira "Configurar regras de proteção de implantação personalizadas".

Aprovar ou rejeitar implantações

Depois que um fluxo de trabalho atinge um trabalho que faz referência a um ambiente com a regra de proteção de implantação personalizada habilitada, GitHub envia uma solicitação POST para um URL que você configura contendo a payload deployment_protection_rule. Você pode escrever sua regra de proteção de implantação para enviar automaticamente solicitações de API REST que aprovem ou rejeitem a implantação com base na carga deployment_protection_rule. Configure suas solicitações de API REST da seguinte maneira.

  1. Valide a solicitação de POST recebida. Para obter mais informações, confira "Validação de entregas de webhooks".

  2. Use um Token Web JSON para autenticar como um GitHub App Para obter mais informações, confira "Efetuar autenticação como um aplicativo GitHub".

  3. Usando o ID de instalação da carga útil do payload do webhook deployment_protection_rule, gere um token de instalação. Para obter mais informações, confira "Sobre a autenticação com um GitHub App".

    curl --request POST \
--url "https://api.github.com/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer {jwt}" \
--header "Content-Type: application/json" \
--data \
'{ \
   "repository_ids": [321], \
   "permissions": { \
      "deployments": "write" \
   } \
}'

  4. Opcionalmente, para adicionar um relatório de status sem executar nenhuma outra ação para o GitHub, envie uma solicitação POST para /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule. No corpo da solicitação, omita o state. Para obter mais informações, confira "Pontos de extremidade da API REST para execuções de fluxo de trabalho". Você pode postar um relatório status na mesma implantação até 10 vezes. Os relatórios de status dão suporte à formatação Markdown e podem ter até 1.024 caracteres.

  5. Para aprovar ou rejeitar uma solicitação, envie uma solicitação POST para /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule. No corpo da solicitação, defina a propriedade state como approved ou rejected. Para obter mais informações, confira "Pontos de extremidade da API REST para execuções de fluxo de trabalho".

  6. Opcionalmente, solicite o status de uma aprovação para um fluxo de trabalho executado enviando uma solicitação GET para /repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals. Para obter mais informações, confira "Pontos de extremidade da API REST para execuções de fluxo de trabalho".

  7. Opcionalmente, revise a implantação no GitHub. Para obter mais informações, confira "Revisar implantações".

Publicar regras de proteção de implantação personalizada no GitHub Marketplace

Você pode publicar o GitHub App no GitHub Marketplace para permitir que os desenvolvedores descubram regras de proteção adequadas e instalem-no em seus repositórios GitHub. Ou você pode navegar pelas regras de proteção de implantação personalizadas existentes para atender às suas necessidades. Para obter mais informações, confira "Sobre o GitHub Marketplace para aplicativos" e "Listar um aplicativo no GitHub Marketplace."