Como usar variáveis de ambiente no GitHub Actions

A implementação de um pipeline de integração e entrega contínuas (CI/CD) é uma ótima prática para aumentar a eficiência da liberação de código funcional para um ambiente de produção. Esses pipelines automatizam o processo de validação de alterações de código para ambientes de produção e fornecem ferramentas para automatizar a liberação para esses ambientes.

Uma maneira comum de fazer isso é usar o sistema de controle de versões existente. O GitHub é um dos mais populares sistemas de controle de versões e disponibiliza o GitHub Actions, uma ferramenta que permite aos desenvolvedores criar, testar e implantar código automaticamente, ajudando a criar pipelines seguros de CI/CD.

Frequentemente, as tarefas do GitHub Actions precisam acessar variáveis de ambiente. Essas variáveis podem ser definidas antecipadamente e acessadas apenas por pipelines executados naquele ambiente específico. Isso permite que os desenvolvedores mudem o comportamento do pipeline de CI/CD de acordo com as variáveis de ambiente, como acionar a compilação de uma versão do aplicativo otimizada para produção antes da implantação.

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

Pré-requisitos

Para seguir este tutorial, você precisa ter:

• Acesso a uma máquina com um editor de código (este tutorial usa o Visual Studio Code) e uma conta no GitHub.

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

Você sabia que temos um plugin da Snyk para o Visual Studio Code que permite verificar o projeto durante o desenvolvimento? Confira a documentação para obter mais informações.

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

Depois de baixar o exemplo de código, crie um repositório no GitHub e adicione-o ao repositório.

O exemplo de código já tem um arquivo de fluxo de trabalho 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

Este arquivo define um fluxo de trabalho simples para compilar o aplicativo Java usando Maven.

Podemos definir variáveis de ambiente no arquivo de configuração YAML do fluxo de trabalho em três níveis: fluxo de trabalho, trabalho e etapa. Esses níveis determinam o escopo das variáveis de ambiente. O nível de fluxo de trabalho usa variáveis de ambiente que se aplicam a todo o fluxo. O nível de trabalho usa variáveis de ambiente que se aplicam a trabalhos específicos. As variáveis de ambiente de etapa se aplicam a etapas específicas.

Vamos explorar em mais detalhes cada uma dessas variáveis.

Variáveis de ambiente de fluxo de trabalho

Para configurar uma variável de ambiente no nível de fluxo de trabalho, precisamos defini-la no nível superior do arquivo YAML. Vamos adicionar o código 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 podemos acessar de qualquer lugar do fluxo de trabalho. Para acessar essa variável, precisamos usar uma sintaxe específica semelhante à adotada no acesso a variáveis de ambiente UNIX. Para usar a variável NAME, precisamos prefixá-la com um cifrão: $NAME.

Vamos adicionar uma nova etapa na linha 23 do fluxo de trabalho para imprimir essa variável:

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

Confirme e envie a mudança para o repositório.

Em seguida, abra o GitHub em um navegador e acesse a guia Actions (Ações) no repositório. Selecione o fluxo de trabalho mais recente em Jobs (Trabalhos) e abra a saída do trabalho de compilação. Clique em Print name (Imprimir nome). Após a expansão, você verá a variável de ambiente impressa, como na imagem abaixo.

As variáveis de ambiente no nível de fluxo de trabalho são úteis para declarar variáveis que se aplicam a cada trabalho e etapa. Por exemplo, podemos usá-las para definir em que tipo de ambiente o fluxo de trabalho está em execução, como desenvolvimento, teste ou produção. Isso pode ser útil para aplicativos Node compilados com npm, pois eles podem usar a variável NODE_ENV. Usando essa variável, cada trabalho pode agir de forma adequada para seu ambiente específico. Você pode saber mais sobre a publicação segura de pacotes de npm neste artigo no blog da Snyk.

Variáveis de ambiente de trabalho

Agora vamos ver como configurar variáveis de ambiente no nível de trabalho e etapa. Elas podem ser configuradas da mesma forma que as variáveis de ambiente de fluxo de trabalho, mas são definidas na seção relevante.

Para a variável de trabalho, precisamos definir a versão do Java da seguinte forma:

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

Agora já 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ê pode notar que, para usar a variável de ambiente JAVA_VERSION, a sintaxe é ligeiramente diferente. Este é um exemplo do uso de contextos para acessar uma variável de ambiente. Os contextos permitem que o GitHub Actions use as variáveis de ambiente em qualquer máquina virtual, já que nem sempre essas tarefas são executadas na mesma máquina virtual em que o ambiente é declarado.

Você pode usar variáveis de ambiente de trabalho para substituir uma variável de ambiente de fluxo de trabalho quando um trabalho específico precisa de um valor diferente da variável de fluxo de trabalho já declarada ou para limitar o escopo da variável a um trabalho específico.

Como mostrado no exemplo acima, podemos usar variáveis de ambiente de trabalho para definir a versão do Java e usá-las em cada etapa. Se quisermos usar uma versão diferente de Java, basta alterá-la em um só lugar para que todas as etapas dentro do trabalho usem automaticamente a nova versão.

Agora que você já está trabalhando em uma ação do GitHub, pode integrar facilmente a Snyk ao GitHub Actions para verificar imediatamente o projeto. Temos ações predefinidas da Snyk para o GitHub disponíveis para sua conveniência. Se você ainda não tiver uma conta Snyk, cadastre-se e integre a verificação ainda hoje.

Variáveis de ambiente de etapa

Também podemos definir variáveis dentro de uma etapa. Veja a seguir um exemplo de uma variável de ambiente de etapa. Altere a etapa Print name (Imprimir nome) no arquivo pipeline.yml para que corresponda a este trecho de código:

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 de etapa limitam o escopo a apenas uma etapa. Isso é útil para tarefas como definir caminhos de arquivos para arquivos de entrada ou saída específicos de uma etapa. No exemplo de código acima, usamos a variável de etapa para definir um texto para impressão.

Veja a seguir um exemplo de arquivo YAML completo do fluxo de trabalho do GitHub mostrando a adição das novas variáveis de ambiente de trabalho e 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'

Faça o check-in deste novo fluxo de trabalho no GitHub e veja a saída, que deve se parecer com a imagem abaixo.

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

Se tentarmos usar a variável de ambiente sem contextos, receberemos este erro:

Isso ocorre porque a setup-java action não tem acesso ao mesmo ambiente. Por isso, o uso de contextos é necessário para tornar a variável disponível.

Uso de variáveis padrão e segredos do GitHub

Além de definir as variáveis de ambiente, o GitHub oferece algumas variáveis padrão que você pode acessar dentro de um fluxo de trabalho. Essas variáveis dão acesso a detalhes como o repositório do GitHub, a ação do GitHub e o aplicativo que executa a ação no fluxo de trabalho. Elas podem ser usadas mesma forma que as variáveis de ambiente definidas pelo usuário. Você precisa acessá-las com contextos quando usa o GitHub Actions, se for o caso.

Os segredos do GitHub são o último tipo de variável de ambiente, e você pode usá-los para variáveis que contêm dados confidenciais. O GitHub criptografa e disponibiliza esses dados dentro do fluxo de trabalho.

Você pode criar variáveis de ambiente criptografadas no GitHub acessando a área Settings (Configurações) do repositório e selecionando Secrets and variables (Segredos e variáveis) e depois Actions (Ações) no menu à esquerda. Em seguida, clique em New repository secret (Novo segredo de repositório) e insira um nome e um valor para o segredo. Crie um segredo chamado API_KEY e atribua a ele um valor aleatório, como mostrado abaixo.

Para usar o segredo dentro do fluxo de trabalho, usamos a mesma sintaxe do uso de contextos para fornecer variáveis de ambiente ao GitHub Actions. No entanto, em vez de prefixar a variável com env., usamos secrets..

1${{secrets.API_KEY}}

Adicione ${{secrets.API_KEY}} à instrução de impressão que criamos dentro do arquivo YAML do fluxo de trabalho. O código deve ficar assim:

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'

Confirme as mudanças e envie-as para o repositório. Acesse a página Actions (Ações) no GitHub para ver a saída da execução mais recente do fluxo de trabalho.

Como podemos ver, o GitHub mascara automaticamente o valor do segredo criptografado para evitar exposições acidentais.

Os segredos do GitHub ajudam a armazenar dados confidenciais, como senhas ou chaves de autorização de API. O uso de segredos evita a codificação desses valores em fluxos de trabalho e o risco de expô-los a entidades externas. Em vez disso, o GitHub criptografa e passa esses valores com segurança às ações dos fluxos de trabalho, garantindo que não apareçam como texto simples nos logs.

Conclusão

Este artigo explicou as variáveis de ambiente do GitHub Actions. Discutimos os três escopos disponíveis para variáveis de ambiente (fluxo de trabalho, trabalho e etapa) e como definir variáveis em cada um desses escopos. Analisamos o uso de contextos para passar variáveis de ambiente para o GitHub Actions e o uso de segredos para criptografar variáveis confidenciais.

As variáveis de ambiente do GitHub Actions permitem que os desenvolvedores criem fluxos de trabalho dinâmicos. Podemos usá-las para alterar o comportamento do fluxo de trabalho de acordo com uma variável padrão do GitHub ou definida pelo usuário. Devemos usar variáveis sempre que quisermos alterar dinamicamente o funcionamento e o momento de execução de um fluxo de trabalho, trabalho ou etapa específico.

O artigo também discutiu o uso de segredos do GitHub como variáveis de ambiente para proteger informações confidenciais. É importante usar segredos do GitHub para variáveis confidenciais, como senhas e chaves de API, para que sejam criptografados e injetados pelo GitHub nos fluxos de trabalho sem risco de exposição.

E lembre-se: a segurança é fundamental! Descubra como a Snyk pode acrescentar uma camada de segurança a fluxos de trabalho do GitHub e saiba mais sobre a integração da Snyk a pipelines de CI/CD para proteger código, contêineres, código aberto e IaCs com uma segurança abrangente.