Gerenciar ambientes para implantação

Sobre ambientes

Os ambientes são usados para descrever um destino de implantação geral, como production, staging ou development. Quando um fluxo de trabalho de GitHub Actions é implantado em um ambiente, o ambiente é exibido na página principal do repositório. Para obter mais informações sobre como ver implantações em ambientes, confira "Exibir o histórico de implantações."

Você pode configurar ambientes com regras de proteção e segredos. Quando um trabalho de fluxo de trabalho faz referência a um ambiente, o trabalho não será iniciado até que todas as regras de proteção do ambiente sejam aprovadas. Um trabalho também não pode acessar segredos definidos em um ambiente até que todas as regras de proteção da implantação tenham êxito.

Opcionalmente, você pode ignorar as regras de proteção de um ambiente e forçar que todos os trabalhos pendentes que fazem referência a ele prossigam. Para obter mais informações, confira "Revisar implantações".

Regras de proteção de implantação

As normas de proteção de implantação exigem a aprovação de condições específicas antes que um trabalho que faz referência ao ambiente possa prosseguir. Você pode usar regras de proteção de implantação para exigir uma aprovação manual, atrasar um trabalho ou restringir o ambiente a determinadas ramificações. Você também pode criar e implementar regras de proteção personalizadas desenvolvidas pelo GitHub Apps para usar sistemas de terceiros no controle de implantações que fazem referência a ambientes configurados no GitHub.

Os sistemas de terceiros podem ser sistemas de observabilidade, sistemas de gerenciamento de alterações, sistemas de qualidade de código ou outras configurações manuais que você usa para avaliar a prontidão antes que as implantações sejam implementadas com segurança nos ambientes.

Revisores necessários

Use os revisores necessários para exigir que uma pessoa ou equipe específica aprove os trabalhos do fluxo de trabalho que fazem referência ao ambiente. Você pode listar até seis usuários ou equipes como revisores. Os revisores devem ter, pelo menos, acesso de leitura ao repositório. Apenas um dos revisores precisam aprovar o trabalho para que prossiga.

Você também tem a opção de impedir auto-revisões para implementações em ambientes protegidos. Se você habilitar essa configuração, os usuários que iniciarem uma implantação não poderão aprovar o trabalho de implantação, mesmo que sejam revisores obrigatórios. Isso garante que as implementações em ambientes protegidos sejam sempre revisadas por mais de uma pessoa.

Para obter mais informações sobre como revisar trabalhos que referenciam um ambiente com revisores obrigatórios, confira "Revisar implantações."

Temporizador de espera

Use o temporizador de espera para atrasar o trabalho por um período específico de tempo depois que o trabalho for inicialmente acionado. O tempo (em minutos) deve ser um número inteiro entre 1 e 43.200 (30 dias).

Ramificações de implantação e marcas

Use ramificações de implantação e marcas para restringir quais ramificações e marcas podem ser implantadas no ambiente. A seguir estão as opções para ramificações de implantação e marcas para um ambiente:

• Sem restrição: nenhuma restrição sobre qual ramificação ou marca pode ser implantada no ambiente.

• Apenas ramificações protegidas: apenas ramificações com regras de proteção de ramificação habilitadas podem ser implantadas no ambiente. Se nenhuma regra de proteção de branch for definida para qualquer branch no repositório, todos os branches poderão implantar. Para obter mais informações sobre regras de proteção de branches, consulte "Sobre branches protegidos".

  Observação: as execuções de fluxo de trabalho de implantação acionadas por tags com o mesmo nome de um branch protegido e forks com branches que correspondem ao nome do branch protegido não podem ser implantadas no ambiente.

• Ramificações selecionadas e marcas: somente ramificações e marcas que correspondam aos padrões de nome especificados podem ser implantadas no ambiente.

  Se você especificar releases/* como uma regra de ramificação de implantação ou marca, apenas uma ramificação ou marca cujo nome comece com releases/ poderá ser implantada no ambiente. (Os caracteres curinga não corresponderão a /. Para fazer a correspondência de ramificações ou marcas que começam com release/ e contêm uma barra única adicional, use release/*/*.) Se você adicionar main como uma regra de ramificação, uma ramificação chamada main também poderá ser implantada no ambiente. Para obter mais informações sobre opções de sintaxe para ramificações de implantação, consulte a documentação do Ruby File.fnmatch.

  Observação: os padrões de nomes devem ser configurados individualmente para ramificações ou marcas.

Permitir que os administradores ignorem as regras de proteção configuradas

Por padrão, os administradores podem ignorar as regras de proteção e forçar implantações para ambientes específicos. Para obter mais informações, confira "Revisar implantações".

Como alternativa, você pode configurar ambientes para não permitir ignorar as regras de proteção para todas as implantações no ambiente.

Regras de proteção de implantação personalizadas

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.com. Para obter mais informações, confira "Criar regras de proteção de implantação personalizadas".

Depois que as regras de proteção de implantação personalizadas forem criadas e instaladas em um repositório, você poderá habilitar a regra de proteção de implantação personalizada para qualquer ambiente no repositório. Para obter mais informações sobre como configurar e habilitar regras de proteção de implantação personalizadas, confira "Configurar regras de proteção de implantação personalizadas".

Segredos do ambiente

Os segredos armazenados em um ambiente só estão disponíveis para trabalhos de fluxo de trabalho que fazem referência ao ambiente. Se o ambiente exigir aprovação, um trabalho não poderá acessar segredos de ambiente até que um dos revisores necessários o aprove. Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

Variáveis de ambiente

As variáveis armazenadas em um ambiente só ficam disponíveis para trabalhos de fluxos de trabalho que fazem referência ao ambiente. Essas variáveis só podem ser acessadas usando o contexto vars. Para obter mais informações, confira "Armazenar informações em variáveis".

Criando um ambiente

Para configurar um ambiente em um repositório de conta pessoal, você deve ser o proprietário do repositório. Para configurar um ambiente em um repositório da organização, você precisa ter acesso de admin.

1. Em GitHub, acesse a página principal do repositório.

2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

   

3. Na barra lateral esquerda, clique em Ambientes.

4. Clique em Novo ambiente.

5. Insira um nome para o ambiente e clique em Configurar ambiente. Os nomes de ambiente não diferenciam maiúsculas de minúsculas. Um nome de ambiente não pode exceder 255 caracteres e deve ser único dentro do repositório.

6. Opcionalmente, especifique as pessoas ou equipes que devem aprovar os trabalhos do fluxo de trabalho que usam esse ambiente. Para obter mais informações, confira "Revisores necessários".

   1. Selecione Revisores necessários.
   2. Insira até até 6 pessoas ou equipes. Apenas um dos revisores precisam aprovar o trabalho para que prossiga.
   3. Opcionalmente, para impedir que os usuários aprovem as execuções de fluxos de trabalho que eles acionaram, selecione Impedir a auto-revisão.
   4. Clique em Salvar regras de proteção.

7. Opcionalmente, especifique o tempo a esperar antes de permitir que os trabalhos do fluxo de trabalho que usam esse ambiente prossigam. Para mais informações, confira "Temporizador de espera".

   1. Selecione Temporizador de espera.
   2. Insira o número de minutos para esperar.
   3. Clique em Salvar regras de proteção.

8. Opcionalmente, não permite ignorar regras de proteção configuradas. Para obter mais informações, confira "Permitir que os administradores ignorem as regras de proteção configuradas".

   1. Desmarque Permitir que os administradores ignorem as regras de proteção configuradas.
   2. Clique em Salvar regras de proteção.

9. Opcionalmente, habilite quaisquer regras personalizadas de proteção de implantação que tenham sido criadas com o GitHub Apps. Para obter mais informações, confira "Regras de proteção de implantação personalizadas".

   1. Selecione a regra de proteção personalizada que você deseja habilitar.
   2. Clique em Salvar regras de proteção.

10. Opcionalmente, especifique quais ramificações e marcas podem ser implantadas nesse ambiente. Para obter mais informações, consulte "Ramificações de implantação e marcas.

    1. Selecione a opção desejada no menu suspenso Branches de implantação.

    2. Se você escolher Ramificações selecionadas e marcas, para adicionar uma nova regra, clique em Adicionar regra de ramificação de implantação ou marca 1. No menu suspenso "Tipo de referência", dependendo da regra que você deseja aplicar, clique em Ramificação ou Marca .

    3. Insira o padrão de nome para a ramificação ou marca que você deseja permitir.

       Observação: os padrões de nomes devem ser configurados individualmente para ramificações ou marcas.

    4. Clique em Adicionar regra.

11. Opcionalmente, adicione segredos de ambiente. Esses segredos só estão disponíveis para trabalhos de fluxo de trabalho que usam o ambiente. Além disso, os trabalhos do fluxo de trabalho que usam este ambiente só podem acessar esses segredos após todas as regras configuradas (por exemplo, revisores obrigatórios). Para obter mais informações, confira "Segredos do ambiente".

    1. Em Segredos do ambiente, clique em Adicionar Segredo.
    2. Insira o nome do segredo.
    3. Insira o valor do segredo.
    4. Clique em Adicionar segredo.

12. Opcionalmente, adicione variáveis de ambiente. Essas variáveis só ficam disponíveis para trabalhos de fluxo de trabalho que usam o ambiente e só podem ser acessadas usando o contexto vars. Para obter mais informações, confira "Variáveis de ambiente".

    1. Em Variáveis de ambiente, clique em Adicionar Variável.
    2. Informe o nome da variável.
    3. Informe o valor da variável.
    4. Clique em Adicionar variável.

Também é possível criar e configurar ambientes por meio da API REST. Para obter mais informações, consulte "Pontos de extremidade da API REST para ambientes de implantação", "Pontos de extremidade da API REST para segredos do GitHub Actions", "Pontos de extremidade da API REST para variáveis do GitHub Actions" e "Pontos de extremidade da API REST para políticas de branch de implantação".

Executar um fluxo de trabalho que faz referência a um ambiente que não existe criará um ambiente com o nome referenciado. Se o ambiente for criado a partir da execução de compilações de página implícitas (por exemplo, de uma fonte de ramificação ou pasta), a ramificação fonte será adicionada como uma regra de proteção ao ambiente. Caso contrário, o novo ambiente criado não terá nenhuma regra de proteção ou segredo configurado. Qualquer pessoa que possa editar fluxos de trabalho no repositório pode criar ambientes por meio de um arquivo de fluxo de trabalho, mas apenas os administradores do repositório podem configurar o ambiente.

Excluir um ambiente

Para configurar um ambiente em um repositório de conta pessoal, você deve ser o proprietário do repositório. Para configurar um ambiente em um repositório da organização, você precisa ter acesso de admin.

A exclusão de um ambiente apagará todos os segredos e regras de proteção associados ao ambiente. Todos os trabalhos que estejam atualmente em espera devido às regras de proteção do ambiente eliminado falharão automaticamente.

1. Em GitHub, acesse a página principal do repositório.

2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

   

3. Na barra lateral esquerda, clique em Ambientes.

4. Ao lado do ambiente que você deseja excluir, clique em .

5. Clique em Entendi. Excluir este ambiente.

Também é possível excluir ambientes por meio da API REST. Para obter mais informações, confira "Pontos de extremidade da API REST para repositórios".

Como os ambientes relacionam-se com as implantações

Quando um trabalho de fluxo de trabalho que referencia um ambiente é executado, ele cria um objeto de implantação com a propriedade environment definida como o nome do ambiente. À medida que o fluxo de trabalho progride, ele também cria objetos de status de implantação com a propriedade environment definida como o nome do ambiente, a propriedade environment_url definida como a URL para o ambiente (se especificado no fluxo de trabalho) e a propriedade state definida como o status do trabalho.

Você pode acessar esses objetos por meio da API REST ou API do GraphQL. Você também pode assinar esses eventos de webhook. Para obter mais informações, confira "Pontos de extremidade da API REST para repositórios," "Objetos" (API do GraphQL) ou "Eventos e cargas de webhook".

Próximas etapas

GitHub Actions fornece várias funcionalidades para gerenciar suas implantações. Para obter mais informações, confira "Implantando com GitHub Actions".