Como usar variáveis de ambiente do GitHub Actions

Play Video: How to Use GitHub Actions Environment Variables and Secrets

Para aumentar a eficiência na entrega de código funcional em um ambiente de produção, é uma ótima prática implementar um pipeline de integração e entrega contínuas (CI/CD). Esses pipelines automatizam a verificação de que uma alteração no código está pronta para ser lançada e oferecem ferramentas para automatizar a publicação em produção.

Uma maneira popular de fazer isso é usar o sistema de controle de versão que você já utiliza. O GitHub é um dos sistemas de controle de versão mais populares e oferece o GitHub Actions, que permite aos desenvolvedores criar, testar e implantar código automaticamente, ajudando a criar pipelines de CI/CD seguros.

É comum que os jobs do GitHub Actions precisem acessar variáveis de ambiente. Essas variáveis podem ser definidas antecipadamente e acessadas apenas pelos pipelines executados naquele ambiente específico. Assim, os desenvolvedores podem alterar o comportamento do pipeline de CI/CD com base nas variáveis de ambiente, por exemplo, para gerar uma versão otimizada do aplicativo para produção antes da implantação.

Este artigo prático apresenta as variáveis de ambiente disponíveis no GitHub Actions e explica quando usá-las.

Pré-requisitos

Para acompanhar este tutorial, você precisa de:

• Acesso a uma máquina com um editor de código (neste tutorial, usamos o Visual Studio Code) e uma conta do GitHub.

• O código de exemplo. Ele contém um aplicativo Java simples que usaremos para demonstrar como as variáveis de ambiente funcionam.

Você sabia que temos um plugin Snyk para Visual Studio Code que permite analisar seu projeto durante o desenvolvimento? Consulte a documentação para saber mais.

O que você pode fazer com as variáveis de ambiente do GitHub Actions

Depois de baixar o código de exemplo, crie um novo repositório no GitHub e adicione o código a ele.

O código de exemplo já inclui um arquivo de workflow do GitHub Actions. O trecho de código abaixo mostra o conteúdo do arquivo .github/workflows/pipeline.yml:

1name: Java CI with Maven
2
3on:
4  push:
5    branches: [ "main" ]
6  pull_request:
7    branches: [ "main" ]
8
9jobs:
10  build:
11
12    runs-on: ubuntu-latest
13
14    steps:
15    - uses: actions/checkout@v3
16    - name: Set up JDK 21
17      uses: actions/setup-java@v3
18      with:
19        java-version: '21'
20        distribution: 'temurin'
21        cache: maven
22    - name: Build with Maven
23      run: mvn -B package --file pom.xml

Esse arquivo define um workflow simples para compilar nosso aplicativo Java com o Maven.

Podemos definir variáveis de ambiente no arquivo de configuração YAML do workflow em três níveis: workflow, job e etapa. Esses níveis determinam o escopo das variáveis de ambiente. No nível do workflow, as variáveis se aplicam ao workflow inteiro. No nível do job, elas se aplicam a jobs específicos. As variáveis de etapa se aplicam a etapas específicas.

Vamos explorar cada uma dessas variáveis em detalhes.

Variáveis de ambiente do workflow

Para configurar uma variável de ambiente no nível do workflow, precisamos defini-la no nível superior do arquivo YAML. Vamos adicionar o trecho a seguir abaixo da variável NAME, no início do arquivo:

1env:
2  NAME: 'Snyk Demo'

Este código define uma variável de ambiente chamada NAME, que agora podemos acessar em qualquer parte do workflow. Para acessá-la, precisamos usar uma sintaxe específica, semelhante à usada para acessar variáveis de ambiente do UNIX. Para usar a variável NAME, devemos adicionar o cifrão como prefixo, transformando-a em $NAME.

Vamos adicionar uma nova etapa ao workflow, na linha 23, para exibir essa variável:

1- name: Print name
2  run: echo "Hello $NAME"

Faça commit dessa alteração e envie-a para o repositório.

Em seguida, abra o GitHub no navegador e acesse a guia Actions do repositório. Selecione o workflow mais recente em Jobs e abra a saída do job de compilação. Clique em Print name. Ao expandir a etapa, você verá que a variável de ambiente foi exibida corretamente, como mostra a imagem abaixo.

As variáveis de ambiente no nível do workflow são úteis para declarar valores aplicáveis a todos os jobs e etapas. Por exemplo, podemos usá-las para definir o tipo de ambiente em que o workflow está sendo executado, como desenvolvimento, teste ou produção. Isso pode ser útil para aplicativos Node compilados com npm, que podem usar a variável NODE_ENV. Com ela, cada job pode agir de acordo com o ambiente específico. Saiba mais sobre como publicar seus pacotes npm com segurança neste artigo do blog da Snyk.

Variáveis de ambiente do job

Agora, vamos ver como configurar variáveis de ambiente para jobs e etapas. Elas podem ser configuradas da mesma forma que as variáveis do workflow, mas devem ser definidas na seção correspondente.

Para a variável do nosso job, queremos definir a versão do Java da seguinte forma:

1jobs:
2  build:
3    env:
4        JAVA_VERSION: '21'

Agora, podemos usar essa variável nas etapas, como fizemos antes.

1steps:
2- uses: actions/checkout@v3
3- name: Set up JDK ${{env.JAVA_VERSION}}
4  uses: actions/setup-java@v3
5  with:
6    java-version: ${{env.JAVA_VERSION}}
7    distribution: 'temurin'
8    cache: maven

No entanto, você talvez perceba que a sintaxe para usar a variável de ambiente JAVA_VERSION é um pouco diferente. Esse é um exemplo do uso de contextos para acessar uma variável de ambiente. Os contextos permitem que o GitHub Actions use nossas variáveis de ambiente em qualquer máquina virtual, já que essas tarefas nem sempre são executadas na mesma máquina virtual em que declaramos as variáveis.

Você pode usar variáveis de ambiente do job para substituir uma variável definida no nível do workflow quando um job específico precisar de outro valor, ou para limitar o escopo da variável a um único job.

Como mostra o exemplo acima, podemos usar variáveis de ambiente do job para definir a versão do Java e usar essa variável em cada etapa. Se no futuro quisermos usar outra versão do Java, basta alterá-la em um só lugar, e todas as etapas do job passarão a usar a nova versão automaticamente.

Como você já está trabalhando com uma action do GitHub, pode integrar a Snyk facilmente ao GitHub Actions e analisar seu projeto agora mesmo. Para facilitar, temos GitHub Actions da Snyk pré-criadas disponíveis. Crie uma conta da Snyk, se ainda não tiver uma, e integre a análise hoje mesmo.

Variáveis de ambiente da etapa

Também podemos definir variáveis em uma etapa. Veja a seguir um exemplo de variável de ambiente de etapa. Altere a etapa Print name no arquivo pipeline.yml para que corresponda ao trecho de código abaixo:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
3  env:
4    BUILD: 'We are currently running the Build job'

As variáveis de ambiente da etapa limitam o escopo a uma única etapa. Isso é útil em tarefas como definir caminhos de arquivos de entrada ou saída específicos para uma etapa. No exemplo acima, usamos a variável da etapa para definir um texto a ser exibido.

A seguir, veja o arquivo YAML completo do workflow do GitHub, com as novas variáveis de ambiente do job e da etapa:

1name: Java CI with Maven
2
3env:
4  NAME: 'Snyk Demo'
5
6on:
7  push:
8    branches: [ "main" ]
9  pull_request:
10    branches: [ "main" ]
11
12jobs:
13  build:
14    env:
15        JAVA_VERSION: '21'
16
17    runs-on: ubuntu-latest
18
19    steps:
20    - uses: actions/checkout@v3
21    - name: Set up JDK ${{env.JAVA_VERSION}}
22      uses: actions/setup-java@v3
23      with:
24        java-version: ${{env.JAVA_VERSION}}
25        distribution: 'temurin'
26        cache: maven
27    - name: Build with Maven
28      run: mvn -B package --file pom.xml
29    - name: Print name
30      run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
31      env:
32        BUILD: 'We are currently running the Build job'

Envie esse novo workflow para o GitHub e confira a saída, que deve ser semelhante à imagem abaixo.

Configuramos a variável de ambiente usando contextos, e a etapa de exibição funciona como esperado.

Se tentássemos usar a variável de ambiente sem contextos, receberíamos o seguinte erro:

Isso acontece porque a setup-java action não tem acesso ao mesmo ambiente. Por isso, é necessário usar contextos para disponibilizar a variável.

Como usar variáveis padrão e secrets do GitHub

Além de definir nossas próprias variáveis de ambiente, o GitHub oferece algumas variáveis padrão que você pode acessar em um workflow. Elas dão acesso a informações como o repositório do GitHub, a action do GitHub e o runner do workflow. Você pode usá-las da mesma forma que as variáveis de ambiente definidas pelo usuário. Quando aplicável, é preciso acessá-las por meio de contextos ao usar o GitHub Actions.

O último tipo de variável de ambiente são os secrets do GitHub. Você pode usá-los para armazenar variáveis com dados confidenciais. O GitHub os criptografa e os disponibiliza no workflow.

Para criar variáveis de ambiente criptografadas no GitHub, acesse Settings no repositório e selecione Secrets and variables, e depois Actions no menu à esquerda. Em seguida, clique em New repository secret e informe um nome e um valor para o secret. Crie um secret chamado API_KEY e atribua a ele um valor aleatório, como mostrado abaixo.

Para usar o secret no workflow, usamos a mesma sintaxe dos contextos para fornecer variáveis de ambiente ao GitHub Actions. No entanto, em vez de usar env. como prefixo, usamos secrets..

1${{secrets.API_KEY}}

Adicione ${{secrets.API_KEY}} à instrução de exibição que já criamos no arquivo YAML do workflow. Ela deve corresponder ao trecho de código abaixo:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION. My API_KEY is ${{secrets.API_KEY}}"
3  env:
4    BUILD: 'We are currently running the Build job'

Faça commit das alterações e envie-as para o repositório. Em seguida, acesse a página Actions no GitHub para ver a saída da execução mais recente do workflow.

Como podemos ver, o GitHub oculta automaticamente o valor do secret criptografado para evitar que ele seja exposto por acidente.

Os secrets do GitHub ajudam a armazenar dados confidenciais, como senhas ou chaves de autorização de API. Com eles, não precisamos inserir esses valores diretamente no workflow e correr o risco de expô-los a terceiros. Em vez disso, o GitHub os criptografa, os disponibiliza com segurança para as actions do workflow e impede que apareçam em texto simples nos logs.

Conclusão

Neste artigo, explicamos as variáveis de ambiente do GitHub Actions. Apresentamos os três escopos disponíveis (workflow, job e etapa) e mostramos como definir variáveis em cada um deles. Em seguida, vimos como usar contextos para fornecer variáveis de ambiente ao GitHub Actions e como usar secrets para criptografar variáveis confidenciais.

As variáveis de ambiente do GitHub Actions permitem que os desenvolvedores criem workflows dinâmicos. Podemos usá-las para mudar o comportamento do workflow com base em uma variável definida pelo usuário ou em uma variável padrão do GitHub. Devemos usar variáveis sempre que quisermos alterar dinamicamente o funcionamento do workflow, de um job ou de uma etapa específica, e também quando eles devem ser executados.

O artigo também abordou o uso dos secrets do GitHub como variáveis de ambiente para proteger informações confidenciais. É importante usar secrets do GitHub para variáveis confidenciais, como senhas e chaves de API, pois o GitHub as criptografa e as insere no workflow sem risco de exposição.

E lembre-se: segurança é essencial! Veja como a Snyk pode adicionar uma camada extra de segurança aos seus workflows do GitHub e saiba mais sobre como integrar a Snyk ao seu pipeline de CI/CD para ter segurança abrangente de código, contêineres, código aberto e IaC.