Personalize seu fluxo de trabalho com variáveis de ambiente

Nesta unidade, você aprenderá a configurar e gerenciar o comportamento específico do ambiente usando variáveis, contextos e scripts personalizados em fluxos de trabalho do GitHub Actions.

Para implementar esse processo, você aprenderá a:

• Use variáveis de ambiente padrão e personalizadas.
• Acesse informações contextuais em fluxos de trabalho.
• Defina variáveis de ambiente em diferentes escopos de fluxo de trabalho.
• Use scripts personalizados com a palavra-chave "run".
• Aplique proteções de ambiente para implantações.

Variáveis e contextos de ambiente padrão

Dentro do fluxo de trabalho das Ações do GitHub, várias variáveis de ambiente padrão podem ser usadas, mas apenas no agente que está executando um trabalho. Essas variáveis padrão diferenciam maiúsculas de minúsculas e se referem a valores de configuração para o sistema e para o usuário atual. Recomendamos que você use essas variáveis de ambiente padrão para fazer referência ao sistema de arquivos em vez de usar caminhos de arquivo codificados. Para usar uma variável de ambiente padrão, especifique $ seguido pelo nome da variável de ambiente.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Além das variáveis de ambiente padrão, você pode usar variáveis definidas como contextos. Contextos e variáveis padrão são semelhantes na medida em que ambos fornecem acesso a informações de ambiente, mas têm algumas diferenças importantes. Embora as variáveis de ambiente padrão possam ser usadas apenas dentro do corredor, você pode usar variáveis de contexto em qualquer ponto do fluxo de trabalho. Por exemplo, as variáveis de contexto permitem executar uma if instrução para avaliar uma expressão antes que o corredor seja executado.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Este exemplo está usando o github.ref contexto para verificar a ramificação que disparou o fluxo de trabalho. Se a ramificação for main, o corredor é executado e imprime "Desdobrando no servidor de produção na ramificação especificada por $GITHUB_REF." A variável de ambiente padrão $GITHUB_REF é usada no corredor para referir-se à ramificação. Observe que as variáveis de ambiente padrão são todas maiúsculas, onde as variáveis de contexto são todas minúsculas.

Informações contextuais disponíveis em um fluxo de trabalho

Use contextos para aceder a informações sobre execuções de fluxo de trabalho, variáveis, ambientes de execução, trabalhos e passos. Cada contexto é um objeto que contém propriedades que podem ser outros objetos ou cadeias de caracteres. Os contextos disponíveis incluem github, env, vars, job, jobs, steps, runnersecrets, , strategy, matrix, needse inputs.

A tabela a seguir lista contextos e descrições de fluxo de trabalho:

Contextos diferentes estão disponíveis em momentos diferentes em uma execução de fluxo de trabalho. Por exemplo, você pode usar o secrets contexto apenas em locais específicos de um trabalho. Além disso, você pode usar algumas funções, como a hashFiles função, apenas em locais específicos.

A tabela a seguir lista restrições para cada contexto e função especial em um fluxo de trabalho. Os contextos listados estão disponíveis apenas para a chave de fluxo de trabalho indicada. Você não pode usá-los em nenhum outro lugar. Você pode usar uma função em qualquer lugar, a menos que ela esteja listada na tabela a seguir.

Variáveis de ambiente personalizadas

Semelhante ao uso de variáveis de ambiente padrão, você pode usar variáveis de ambiente personalizadas em seu arquivo de fluxo de trabalho. Para criar uma variável personalizada, você precisa defini-la em seu arquivo de fluxo de trabalho usando o env contexto. Se você quiser usar o valor de uma variável de ambiente dentro de um corredor, você pode usar o método normal do sistema operacional do corredor para ler variáveis de ambiente.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Definir variáveis de ambiente personalizadas em um fluxo de trabalho

Você pode definir variáveis de ambiente que têm escopo para todo o fluxo de trabalho usando env no nível superior do arquivo de fluxo de trabalho. Definir o escopo do conteúdo de um trabalho em um fluxo de trabalho usando jobs.<job_id>.env. Você pode definir o escopo de uma variável de ambiente em uma etapa específica dentro de um trabalho usando jobs.<job_id>.steps[*].env.

Veja um exemplo que mostra os três cenários em um arquivo de fluxo de trabalho:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Usar um contexto padrão em um fluxo de trabalho

A plataforma GitHub define variáveis de ambiente padrão. Eles não são definidos em um fluxo de trabalho, mas você pode usar uma variável de ambiente padrão em um fluxo de trabalho no contexto apropriado. A maioria dessas variáveis, além de CI, começam com GITHUB_* ou RUNNER_*. Os dois últimos tipos não podem ser substituídos. Além disso, essas variáveis padrão têm uma propriedade de contexto correspondente e com nome semelhante. Por exemplo, a RUNNER_* série de variáveis padrão tem uma propriedade de contexto correspondente de runner.*.

Veja um exemplo de como acessar variáveis padrão em um fluxo de trabalho aplicando estes métodos:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Para obter mais informações, consulte Variáveis de ambiente padrão.

Passar variáveis de ambiente personalizadas para um fluxo de trabalho

Você pode transmitir variáveis de ambiente personalizadas de uma etapa de um trabalho de fluxo de trabalho para as etapas seguintes no trabalho. Gere um valor em uma etapa de um trabalho e atribua o valor a uma variável de ambiente nova ou existente. Em seguida, você grava o par variável/valor no arquivo de ambiente GITHUB_ENV. Usando a palavra-chave run, pode utilizar o ficheiro de ambiente numa ação ou a partir de um comando shell na tarefa de fluxo de trabalho.

A etapa que cria ou atualiza a variável de ambiente não tem acesso ao novo valor, mas todas as etapas subsequentes em um trabalho têm acesso.

Aqui está um exemplo:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Adicionar proteções ambientais

Você pode adicionar regras de proteção para ambientes definidos para seu repositório GitHub.

Para adicionar um ambiente, no teu repositório:

1. Selecione Configurações.

   

2. No painel esquerdo, selecione Ambiente.

   

3. Selecione o botão Novo ambiente para adicionar e configurar um ambiente e adicionar proteções.

   

Sobre ambientes

Use ambientes para descrever um destino de implantação geral, como produção, preparo ou desenvolvimento. Quando um fluxo de trabalho do GitHub Actions é implantado em um ambiente, o ambiente aparece na página principal do repositório. Você pode usar ambientes para exigir aprovação para que um trabalho prossiga, restringir quais ramificações podem iniciar um fluxo de trabalho, controlar implantações mediante regras personalizadas de proteção de implantação, ou limitar o acesso a informações confidenciais.

Cada trabalho em um fluxo de trabalho pode fazer referência a um ambiente. Todas as regras de proteção definidas para o ambiente devem passar antes que um trabalho que faça referência ao ambiente seja enviado a um corredor. O trabalho pode aceder aos segredos do ambiente somente depois que o trabalho é enviado para um corredor.

Quando um fluxo de trabalho faz referência a um ambiente, o ambiente aparece nas implantações do repositório.

Regras de proteção do ambiente

As regras de proteção de implantação ambiental exigem condições específicas para serem aprovadas antes que um trabalho que faça referência ao ambiente prossiga. Você pode usar regras de proteção de implantação para exigir uma aprovação manual, atrasar um trabalho ou restringir o ambiente a ramificações específicas. Você também pode criar e implementar regras de proteção personalizadas alimentadas por aplicativos GitHub para usar sistemas parceiros para controlar implantações que fazem referência a ambientes configurados no GitHub.

Aqui está uma explicação dessas regras de proteção:

• Regras de proteção de revisores necessárias. Use esta regra para exigir que uma pessoa ou equipe específica aprove trabalhos de fluxo de trabalho que façam referência ao ambiente. Você pode listar até seis usuários ou equipes como revisores. Os revisores devem ter pelo menos permissões de leitura para o repositório. Apenas um revisor necessário deve aprovar o trabalho para que ele prossiga.

  Você também pode impedir revisões automáticas para implantações em um ambiente protegido. Se você habilitar essa configuração, os usuários que iniciam uma implantação não poderão aprovar o trabalho de implantação, mesmo que sejam um revisor necessário. Ao habilitar as autoavaliações, ele garante que mais de uma pessoa analise as implantações em ambientes protegidos.

  Para obter mais informações sobre como revisar trabalhos que fazem referência a um ambiente com revisores necessários, consulte Revisar implantações.

• Regras de projeção do cronómetro de espera. Você pode usar uma regra de proteção com temporizador de espera para atrasar um trabalho por um período específico de tempo após o trabalho ser inicialmente acionado, antes que a implantação do ambiente continue. O tempo (em minutos) deve ser um número inteiro entre 1 e 43.200 (30 dias). O tempo de espera não conta para o seu tempo faturável.

• Regras de proteção de ramificações e tags. Você pode usar regras de proteção de ramos e tags de implementação para restringir quais tags e ramos são usados para implementar no ambiente. Você tem várias opções para regras de proteção de ramificação e tag de implantação para um ambiente.

  • Nenhuma restrição define nenhuma restrição sobre qual ramificação ou tag pode ser implantada no ambiente.
  • Somente ramificações protegidas permite que somente ramificações com regras de proteção de ramificação habilitadas sejam implantadas no ambiente. Se nenhuma regra de proteção de ramificação for definida para qualquer ramificação no repositório, todas as ramificações poderão ser implantadas. A configuração Ramificações e tags selecionadas garante que somente ramificações e tags que correspondam aos padrões de nome especificados possam ser implantadas no ambiente.
  • Se especificar releases/* como uma regra de ramificação ou tag de implantação, somente uma ramificação ou tag com um nome que começa com releases/ poderá ser implantada no ambiente. (Os caracteres curinga / não correspondem. Para corresponder a branches ou tags que começam com release/ e contêm outra única barra, use release/*/*.) Se adicionar main como uma regra de branch, um branch chamado main também poderá ser implementado no ambiente.

• Regras personalizadas de proteção de implantação. Você pode criar regras de proteção personalizadas para controlar implantações e utilizar serviços de parceiros. Por exemplo, você pode usar 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 e fornecer aprovações automatizadas para implantações no GitHub.

  Depois de criar regras de proteção de implantação personalizadas e instalá-las em um repositório, você pode habilitar a regra de proteção de implantação personalizada para qualquer ambiente no repositório.

  

Scripts no seu fluxo de trabalho

Nos exemplos de trechos de fluxo de trabalho anteriores, a run palavra-chave é usada para imprimir uma cadeia de caracteres de texto. Como a run palavra-chave diz ao trabalho para executar um comando no corredor, você usa a run palavra-chave para executar ações ou scripts.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

Neste exemplo, você usa npm para instalar o pacote de teste de bats software usando a run palavra-chave. Você também pode executar um script como uma ação. Você pode armazenar o script em seu repositório, geralmente feito em um .github/scripts/ diretório e, em seguida, fornecer o caminho e o tipo de shell usando a run palavra-chave.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash