Aprovações em um fluxo de trabalho no Github Actions
A aprovação no GitHub Actions é uma etapa manual que pausa o workflow até que uma pessoa autorizada revise e libere a execução do próximo job. Neste artigo, você vai configurar essa etapa do zero, usando environments e a regra de required reviewers do GitHub.
O GitHub Actions é a ferramenta de automação de fluxos de trabalho (workflows) integrada ao GitHub. Com ela, automatizamos o fluxo de integração e entrega de uma aplicação diretamente no repositório.
O objetivo aqui é mostrar as configurações necessárias para que um processo só rode depois de uma revisão. Assim, o workflow solicita o review para uma lista predefinida de usuários, e um aviso amarelo aparece na tela enquanto a aprovação não chega.
Contexto: CI/CD e aprovação no GitHub Actions
A automação das etapas de entrega e implantação de uma aplicação (backend, frontend ou mobile) recebe o nome de CI/CD, sigla para Continuous Integration e Continuous Delivery. Na prática, cada push ou pull request dispara uma sequência de passos que compila, testa e publica o software.
Você cria essas etapas de acordo com as necessidades do seu projeto. Além disso, o GitHub Actions executa os jobs na ordem que você define, e eles podem ter dependências entre si.
Por exemplo, uma etapa de testes precisa rodar antes do build final da aplicação. Caso ela falhe, o fluxo para ali e as etapas seguintes não acontecem.
Essa ordem é justamente o que torna a aprovação no GitHub Actions útil. Afinal, você consegue colocar um ponto de controle humano entre dois jobs, normalmente antes do deploy em produção.
Para contextualizar o processo, vamos primeiro criar um workflow base com três ambientes. Em seguida, adicionamos a regra de aprovação no último deles.
Se você ainda não tem o Git e o GitHub configurados na sua máquina, vale ler antes o guia de Git e GitHub: instalação, configuração e primeiros passos.
Criando o workflow base no GitHub Actions
O exemplo completo deste artigo está disponível no repositório de exemplo do workflow de aprovação. Você pode cloná-lo ou repetir os passos no seu próprio repositório.
Primeiro, dentro do repositório no GitHub, crie o diretório .github/workflows. O GitHub procura os arquivos de workflow sempre nesse caminho.
Em seguida, dentro de .github/workflows, crie um arquivo chamado main.yaml com o conteúdo abaixo.
# .github/workflows/main.yaml
name: Running
on:
push: # quando o push for feito para a master
branches:
- master
jobs:
dev:
runs-on: ubuntu-latest
steps:
- name: Development
run: echo 'development'
stg:
needs: dev
runs-on: ubuntu-latest
steps:
- name: Staging
run: echo 'staging'
prd:
needs: stg
runs-on: ubuntu-latest
steps:
- name: Production
run: echo 'production'
O arquivo cria três jobs: dev, stg e prd. Cada um deles apenas imprime um texto no terminal, porque o foco aqui é o fluxo, não o deploy em si.
Esses jobs representam três ambientes em que o deploy de uma aplicação pode acontecer. Ou seja, desenvolvimento, homologação (staging) e produção.
Além disso, os jobs dependem uns dos outros por meio da chave needs. Dessa forma, prd só roda se stg terminar com sucesso, e stg só roda depois de dev.
Segundo a documentação oficial, quando um job falha ou é ignorado, os jobs que dependem dele também são ignorados. A exceção fica para quem usa uma expressão condicional como always().
Vale lembrar que existem outras estratégias de deploy. Por exemplo, alguns times preferem branches específicas para cada ambiente.
Agora faça o push para a sua branch principal, que no exemplo se chama master. Logo depois, acesse o menu Actions do repositório e clique na execução em andamento.
Você vai encontrar os três jobs executados em sequência, como na imagem a seguir.
Até aqui, nenhuma aprovação no GitHub Actions interrompe o fluxo. Portanto, qualquer push na master leva o código direto até o job de produção.
O que é a etapa de aprovação no GitHub Actions
A etapa de aprovação no GitHub Actions é uma pausa manual no workflow. Nela, um usuário da lista de revisores analisa a execução e libera o próximo job que referencia um ambiente.
O recurso que viabiliza isso se chama environment. Um environment é um ambiente de implantação, como production, que pode ter regras de proteção, secrets e variáveis próprios.
De acordo com a documentação oficial sobre environments, um job que referencia um environment precisa cumprir as regras de proteção dele antes de rodar. Além disso, ele só acessa os secrets do ambiente depois disso.
Entre essas regras, a que nos interessa é a de required reviewers. Ela transforma o job em um ponto de aprovação no GitHub Actions, já que o job aguarda até que alguém da lista aprove.
Configurando o environment para aprovação no GitHub Actions
As regras de proteção e as chaves de um ambiente ficam nas configurações de environment. Por isso, o primeiro passo acontece nos Settings do repositório em que você criou o workflow.
Dentro do repositório, clique em Settings.
Depois, no menu lateral esquerdo, clique na opção Environments.
Criando o environment production
Na tela de Environments, clique em New environment.
Na caixa de texto, informe o nome do ambiente, que o código do workflow vai referenciar mais adiante. No exemplo, usamos production, e então clique em Configure environment.
Segundo a documentação, o nome do environment não diferencia maiúsculas de minúsculas e pode ter até 255 caracteres. Além disso, ele precisa ser único dentro do repositório.
Ativando required reviewers
Na seção Environment protection rules, marque a opção Required reviewers.
Em seguida, informe os usuários ou equipes que poderão aprovar as execuções desse ambiente. Você pode listar até seis usuários ou equipes da sua organização.
No entanto, basta que apenas um deles aprove para o job seguir. A documentação também exige que os revisores tenham, no mínimo, acesso de leitura ao repositório.
Por fim, clique em Save protection rules para salvar as alterações.
Referenciando o environment no workflow
Com o ambiente pronto, falta dizer ao workflow qual job depende da aprovação no GitHub Actions. Para isso, abra o arquivo .github/workflows/main.yaml e adicione a chave environment no job que deve esperar a revisão.
No nosso caso, a aprovação no GitHub Actions fica no job prd. Então a linha que entra no arquivo é esta:
environment: production
O arquivo YAML completo com aprovação no GitHub Actions
Veja como fica o workflow completo depois da alteração.
# .github/workflows/main.yaml
name: Running
on:
pull_request: # modificado para visualizar o resultado na alteração do PR
types: [opened, reopened, synchronize]
jobs:
dev:
runs-on: ubuntu-latest
steps:
- name: Development
run: echo 'development'
stg: # homologação
needs: dev
runs-on: ubuntu-latest
steps:
- name: Staging
run: echo 'staging'
prd: # aprovação
needs: stg
runs-on: ubuntu-latest
environment: production # com a regra de aprovação
steps:
- name: Production
run: echo 'production'
Repare que mudamos o gatilho de push para pull_request. Com isso, o workflow roda quando alguém abre, reabre ou atualiza um pull request, o que facilita visualizar o resultado.
Para comparar as duas versões linha a linha, abra o pull request com a alteração do workflow.
Usando name e url no environment
A chave environment também aceita um objeto com name e url. Nesse caso, o GitHub exibe a URL na execução, o que ajuda a abrir o ambiente publicado com um clique.
prd:
needs: stg
runs-on: ubuntu-latest
environment:
name: production
url: https://example.com # endereço exibido na execução
steps:
- name: Production
run: echo 'production'
Além disso, a documentação informa que tanto name quanto url aceitam expressões. Assim, você pode montar o nome do ambiente a partir de variáveis ou do contexto do workflow.
Outro detalhe importante: se o workflow referenciar um environment que ainda não existe, o GitHub cria um ambiente com esse nome. Porém, ele nasce sem regras de proteção, então a aprovação só funciona depois que você configurar os revisores.
Visualizando a aprovação no GitHub Actions
Depois do push da alteração, entre novamente em Actions e clique no workflow em execução do último commit. Os jobs dev e stg rodam normalmente, mas o prd fica aguardando.
Revisando e aprovando o deploy
A partir daqui, os revisores definidos na lista podem liberar a execução. Para isso, clique em Review deployments.
Então, uma janela se abre para você selecionar o ambiente que deseja aprovar. Nela também existe um campo opcional para deixar um comentário sobre a decisão.
Depois da revisão, clique em Approve and deploy para que o job siga em frente. Caso prefira barrar a execução, a opção Reject interrompe o processo e, segundo a documentação, faz o workflow falhar.
Com o fluxo aprovado, o job de produção roda. Além disso, o histórico da execução guarda quem aprovou, para qual ambiente e com qual comentário.
Esse registro da aprovação no GitHub Actions é valioso para auditoria. Afinal, você sabe exatamente quem liberou cada deploy e em que momento.
Outras regras de proteção para aprovação no GitHub Actions
A regra de revisores não é a única opção disponível. Na prática, você pode combinar a aprovação no GitHub Actions com outras proteções do mesmo ambiente.
Prevent self-review e wait timer
A opção Prevent self-review impede que a pessoa que disparou o workflow aprove a própria execução. Dessa forma, cada deploy passa pelos olhos de pelo menos mais alguém do time.
Essa configuração faz diferença em times pequenos. Isso porque, sem ela, o autor do pull request pode estar na lista de revisores e liberar o próprio código.
O wait timer atrasa o início do job por um tempo fixo depois que ele é disparado. Segundo a documentação, o valor fica entre 1 e 43.200 minutos, o que equivale a 30 dias.
Por exemplo, você pode esperar alguns minutos entre o deploy em staging e o de produção para observar métricas. Além disso, o tempo de espera não conta como minutos faturáveis.
Branches, bypass e secrets por ambiente
A regra Deployment branches and tags define quais branches e tags podem fazer deploy no ambiente. As opções são sem restrição, apenas branches protegidas ou branches e tags selecionadas por padrões de nome.
Assim, você garante que somente a branch principal chegue em produção. Uma branch de feature, por exemplo, fica bloqueada mesmo que alguém tente aprovar.
Já em relação ao bypass, por padrão os administradores podem ignorar as regras de proteção, inclusive a de revisores. Porém, você pode desativar esse comportamento nas configurações do ambiente.
Quando o bypass está liberado, o administrador usa a opção Start all waiting jobs e informa um motivo. Por isso, vale decidir com o time se essa porta deve continuar aberta.
Cada environment pode ter secrets e variáveis próprios. Segundo a documentação, os secrets de um ambiente só ficam disponíveis para jobs que referenciam esse ambiente.
Além disso, o job só lê esses secrets depois que as regras de proteção passam. Ou seja, a connection string de produção nunca aparece para um job que ainda não recebeu a aprovação no GitHub Actions.
As variáveis de ambiente funcionam de forma parecida, mas guardam valores não sensíveis. Você as acessa no workflow pelo contexto vars.
Disponibilidade da aprovação no GitHub Actions por plano
Antes de planejar a aprovação no GitHub Actions, confira o plano da sua conta ou organização. A documentação informa que environments estão disponíveis para repositórios públicos em todos os planos atuais.
Em repositórios privados ou internos, porém, as regras mudam. Os planos Pro e Team liberam environments e secrets de ambiente, enquanto o plano Free não oferece environments para repositórios privados.
Além disso, as regras extras de proteção, como required reviewers e wait timer, têm restrições próprias. Nos planos Free, Pro e Team, a documentação as limita a repositórios públicos, então confirme a disponibilidade antes de depender delas em um repositório privado.
A documentação também informa que um ambiente aceita no máximo seis regras de proteção de deployment habilitadas ao mesmo tempo. Na prática, esse limite raramente atrapalha um fluxo comum.
Boas práticas para aprovação no GitHub Actions
Uma etapa manual só agrega valor quando a revisão é real. Por isso, algumas práticas ajudam a manter a aprovação no GitHub Actions útil, e não apenas burocrática.
Primeiro, coloque a revisão somente onde o risco justifica. Em geral, isso significa produção, enquanto desenvolvimento e homologação seguem automáticos.
Em seguida, prefira equipes no lugar de pessoas individuais na lista de revisores. Assim, férias ou trocas no time não travam um deploy importante.
Também vale ativar o Prevent self-review em ambientes críticos. Dessa forma, nenhuma alteração chega à produção sem um segundo par de olhos.
Outra prática é guardar os secrets de produção no environment, e não nos secrets gerais do repositório. Com isso, eles só ficam acessíveis depois da aprovação no GitHub Actions.
Por fim, use o campo de comentário da revisão. Ele cria um histórico que explica por que cada deploy aconteceu ou foi rejeitado.
Se você quer evoluir o pipeline, veja como criar workflows reutilizáveis no GitHub Actions. Além disso, o artigo sobre deploy de ASP.NET com GitHub Actions e Microsoft Azure mostra um cenário real de publicação.
Recapitulando
As configurações de ambiente permitem customizar cada environment com regras de proteção e restrições. Além disso, elas guardam chaves e variáveis específicas de cada ambiente.
Esse recurso aparece com frequência na separação de ambientes de implantação como development, staging e production. Você pode visualizar os ambientes criados na página principal do seu repositório.
Conclusão
Neste artigo, você criou um workflow com três ambientes e adicionou uma etapa de aprovação no GitHub Actions antes do job de produção. Para isso, bastou criar o environment, ativar required reviewers e referenciar o ambiente no YAML.
E aí, aprendeu a criar etapas de aprovação no GitHub Actions? Para aprender mais sobre Git, GitHub e outros fundamentos, confira o curso Fundamentos do Azure, Git, GitHub e DevOps no balta.io.
Para conhecer as demais opções das configurações de ambiente, consulte a documentação oficial do GitHub. Além disso, o artigo sobre Azure e GitHub Actions complementa o tema com a integração entre as duas plataformas.
FAQ
Quantos revisores posso adicionar em um environment?
Você pode listar até seis usuários ou equipes como required reviewers. Basta que um deles aprove para o job continuar.
O que acontece se o revisor rejeitar o deploy?
O job não roda e o workflow falha. O comentário da revisão fica registrado no histórico da execução.
Preciso criar o environment antes de referenciá-lo no YAML?
Não é obrigatório, porque o GitHub cria o ambiente automaticamente quando o workflow o referencia. Porém, ele nasce sem regras de proteção, então a revisão só funciona depois da configuração.
Quem disparou o workflow pode aprovar a própria execução?
Pode, a menos que você ative a opção Prevent self-review no environment. Com ela ativa, outra pessoa da lista precisa aprovar.
A etapa de aprovação funciona em repositórios privados?
Depende do plano da conta ou organização. Consulte a documentação de environments para confirmar quais regras estão disponíveis no seu plano.