Que o Github Actions é uma ferramenta muito interessante e útil, você já deve saber. Por isso, neste artigo vamos nos aprofundar em como trabalhar com variáveis de ambiente e com secrets com ele.
Vamos começar com como usar variáveis de ambiente dentro dos seus workflows do Github Actions, para usar com scripts, ou não. Em seguida, vamos ver como usar segredos através de variáveis de ambiente dentro dos seus workflows do Github Actions.
Mas o que são variáveis de ambiente?
Variáveis de ambiente são valores string não nulas, armazenadas em uma “lista” de chave-valor no sistema operacional / ambiente, que podem ser usadas por programas executados na máquina.
Essas configurações podem ser recuperadas pelos processos do sistema (obs: os sub-processos herdam as variáveis de ambiente do processo-pai).
É possível extrair e manipular essas variáveis através de scripts ou programas.
Além disso, é possível que cada linguagem de programação tenha sua nomenclatura para usá-los. Veja alguns exemplos:
PYTHON – valor = os.environ(“NOME_DA_VARIAVEL”);
JAVA – String valor = System.getenv(“NOME_DA_VARIAVEL”);
GOLANG – valor := os.Getenv(“NOME_DA_VARIAVEL”);
NODE – const VALOR = process.env.NOME_DA_VARIAVEL.Como usar variáveis de ambiente com Github Actions?
A própria sintaxe dos workflows (documentação) foi desenhada para poder configurar variáveis de ambiente em diversos níveis dos nossos workflows:
- A nível do workflow: para permitir que qualquer job ou step possam usá-las.
- A nível de job: para permitir que qualquer step do job possa usá-las.
- A nível de step: para permitir usá-las apenas neste lugar.
A implementação é a mesma em todos os casos (só a indentação que vai mudar de acordo com o lugar onde foi colocado), conforme o seguinte exemplo:
env:
MY_VAR: Hi there! My name is
FIRST_NAME: Mona
MIDDLE_NAME: The
LAST_NAME: OctocatSe você deseja usar o valor de uma variável de ambiente dentro de um runner, deve usar o contexto env (por exemplo: ${{ env.NOME_DA_VARIAVEL }} ) para conseguir acessar a variável.
Já, caso deseje usar o valor da variável dentro de um script ou um step, você pode usar o método normal do sistema operacional do runner ou da linguagem (por exemplo: $NOME_DA_VARIAVEL em shell).
Ponto de atenção: Quando mais de uma variável de ambiente é definida com o mesmo nome, o GitHub usa a variável de ambiente mais específica. Por exemplo, uma variável de ambiente definida em um step substituirá variáveis de um job e/ou de um workflow pelo mesmo nome enquanto o step é executado.
É importante destacar também que os próprios runners que são usados nos workflows (windows, macOS e ubuntu) também vêm com suas variáveis de ambiente padrão e podem ser bastante relevantes dependendo do contexto em que você está trabalhando. Lembrando que os comandos executados em ações ou etapas podem criar, ler e modificar as variáveis do ambiente.
Dessa maneira, é possível usar, por exemplo:
- GITHUB_ACTOR: Nome da pessoa ou aplicativo que iniciou o fluxo de trabalho. Por exemplo, octocat.
- GITHUB_REPOSITORY: Nome do repositório e do proprietário. Por exemplo, octocat/Hello-World.
- GITHUB_REF: Branch ou ref tag que acionou o fluxo de trabalho. Por exemplo, refs/heads/feature-branch-1. (Se não houver branch ou tag disponível para o tipo de evento, a variável não existirá.)
Entre outras variáveis…
Inclusive, a lista completa dessas variáveis padrão pode ser encontrada aqui.
Aplicação das variáveis de ambiente
Vamos criar um workflow onde serão configuradas variáveis de ambiente nos 3 níveis que comentamos acima (workflow, job e step) para depois imprimir os valores dessas variáveis num step através de comandos shell.
Segue abaixo o workflow completo:
Para quem quiser ver um workflow parecido sendo executado, criei um repositório de demo com vários exemplos de uso do Github Actions.
No Actions, o output desse job é apresentado conforme na imagem abaixo:
Mas o que são secrets?
Secrets (ou segredos, em português) são variáveis de ambiente que não podem ser compartilhadas com ninguém que não seja autorizado. São dados sigilosos, geralmente específicos de um contexto, por exemplo, de uma organização, um repositório, uma equipe…
Exemplos de secrets:
- o usuário e uma senha para acessar uma ferramenta;
- a chave para consumir uma API;
- um token ou uma credencial de acesso;
- o número de um documento (CPF, Passaporte etc).
Como usar Secrets com Github Actions?
Antes de entrar em detalhes sobre como usar Secrets nos nossos workflows, vale a pena lembrar como criar segredos no Github e quais são as regras a seguir para nomear os seus segredos. A própria documentação do Github está disponível em português:
- Link para criação de segredos.
- Link para as regras a seguir para nomear os segredos.
Observação: O GitHub usa uma caixa selada libsodium para ajudar a garantir que os segredos sejam criptografados antes de chegarem ao GitHub e permaneçam criptografados até que você os use em um fluxo de trabalho.
Beleza. Adicionamos novos segredos (de maneira segura) ao nosso repositório ou à nossa organização. Mas como vamos usá-los nos nossos workflows?
Para usar o valor de uma variável de ambiente dentro de um runner era necessário usar o contexto env (por exemplo: ${{ env.NOME_DA_VARIAVEL }} ) para conseguir acessar a variável.
Para os secrets, o funcionamento é o mesmo que para as variáveis de ambiente, só que usando o contexto secrets, conforme o exemplo abaixo:
steps:
- name: Hello world action
with: # Configura o segredo como uma entrada
super_secret: ${{ secrets.SuperSecrett }}
env: #Ou como uma variável de ambiente
super_secret: ${{ secrets.SuperSecrett }}Observamos no código acima que é possível configurar um segredo como variável de ambiente ou como uma entrada.
Observação: Usar o contexto é a única maneira de acessar os segredos através do workflow. Não é recomendado usar o método normal do sistema operacional do runner (por questão de segurança óbvias) ou da linguagem (por exemplo: $NOME_DA_VARIAVEL em shell).
Aplicação de secrets
Vamos criar um workflow onde será configurado um SECRET_VALUE para depois manipular essa variável num step através de comandos shell.
Segue abaixo o workflow completo:
Para quem quiser ver um workflow parecido sendo executado, criei um repositório de demo com vários exemplos de uso do Github Actions.
Neste workflow, além de usar parte da implementação apresentada acima, usei um Personal Access Token (PAT) como segredo (ACCESS_TOKEN) em uma ação para conseguir clonar um repositório privado.
Observação: Um ponto de atenção aqui é que o segredo GITHUB_TOKEN disponibilizado em todos os workflows do github actions não tem necessariamente as mesmas permissões que você pode obter através do PAT. Consequentemente, avaliem qual usar dependendo do escopo do workflow que estão usando.
No Actions, o output desse job é apresentado conforme na imagem abaixo:
Podemos ver que se tentamos mostrar o valor do segredo configurado através da variável de ambiente (SECRET_VALUE), ele foi ofuscado pelo Actions (aparece *** na linha 8 do primeiro step).
O segredo usado como input da ação do segundo step (ACCESS_TOKEN) foi usado para clonar o repositório privado e também aparece ofuscado na linha 6.
Em outras palavras, os segredos foram usados conforme esperado!
Vale a pena destacar também que existem limites sobre a quantidade de segredos que podem ser armazenados em um repositório. Os detalhes podem ser encontrados na documentação oficial.
Conclusão
Antes de concluirmos, que tal receber os conteúdos da Zup no seu e-mail? Para isso, baste se inscrever na newsletter!
Por hoje é isso! Espero que este artigo tenha deixado mais claro como usar variáveis de ambiente e secrets no Github Actions para usar com seus workflows ou scripts nos seus repositórios do Github.
Quem quiser aprofundar no Github Actions para testar variáveis de ambiente, secrets e muito mais é só criar seu repositório com seus workflows e experimentar. Isso, pois o plano FREE da plataforma permite você testar seus fluxos de trabalhos em repositórios públicos sem limites de tempo.
Lembrando que a documentação do Github Actions em português é muito boa e vale uma lida.
Referências:
