Personalizar seu fluxo de trabalho com variáveis de ambiente

Nesta unidade, você aprenderá a configurar e gerenciar comportamentos específicos 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 escopos de fluxo de trabalho diferentes.
• Use scripts personalizados com a palavra-chave run.
• Aplicar proteções de ambiente para implantações.

Variáveis de ambiente e contextos padrão

No fluxo de trabalho do GitHub Actions, várias variáveis de ambiente padrão estão disponíveis para uso, mas somente dentro do executor que está executando um trabalho. Essas variáveis padrão diferenciam maiúsculas e minúsculas e se referem aos valores de configuração do sistema e do 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 embutidos em código. 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, pois ambos fornecem acesso a informações de ambiente, mas têm algumas diferenças importantes. Embora variáveis de ambiente padrão possam ser usadas somente dentro do executor, você pode usar variáveis de contexto a qualquer momento no fluxo de trabalho. Por exemplo, as variáveis de contexto permitem que você execute uma instrução if para avaliar uma expressão antes de executar o executor.

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 contexto github.ref para verificar o branch que disparou o fluxo de trabalho. Se o branch for main, o executor será executado e imprimirá “Implantando no servidor de produção no branch $GITHUB_REF”. A variável de ambiente padrão $GITHUB_REF é usada no executor para se referir ao branch. Observe que as variáveis de ambiente padrão são todas maiúsculas, já as variáveis de contexto são todas minúsculas.

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

Use contextos para acessar informações sobre execuções de fluxo de trabalho, variáveis, ambientes de executor, trabalhos e etapas. 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, runner, secrets, , 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 em uma tarefa. Além disso, você pode usar algumas funções, como a hashFiles função, somente em locais específicos.

A tabela a seguir lista as 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 no arquivo de fluxo de trabalho usando o contexto env. Se você quiser usar o valor de uma variável de ambiente dentro de um executor, use o método normal do sistema operacional do executor para ler as 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 com escopo para todo o fluxo de trabalho usando env no nível superior do arquivo de fluxo de trabalho. Delimite o conteúdo de uma tarefa 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.

Aqui está um exemplo que mostra todos 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, exceto 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 de nome semelhante. Por exemplo, a RUNNER_* série de variáveis padrão tem uma propriedade de contexto correspondente de runner.*.

Aqui está 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, veja 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 existente ou nova. Em seguida, você escreve o par variável/valor no arquivo de ambiente GITHUB_ENV. Use o arquivo de ambiente em uma ação ou em um comando de shell no trabalho de fluxo de trabalho usando a palavra-chave run.

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.

Veja 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 de ambiente

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

Para adicionar um ambiente, no seu 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 os 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 branches podem iniciar um fluxo de trabalho, bloquear implantações usando regras de proteção de implantação personalizadas ou limitar o acesso a segredos.

Cada trabalho em um fluxo de trabalho pode referenciar um ambiente. Todas as regras de proteção definidas para o ambiente devem ser atendidas antes que um trabalho que referencie o ambiente seja enviado a um executor. O trabalho pode acessar os segredos do ambiente somente depois que o trabalho é enviado para um executor.

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 da implantação do ambiente exigem o cumprimento de condições específicas para que um trabalho que referencia o ambiente prossiga. Você pode usar regras de proteção de implantação para exigir uma aprovação manual, atrasar uma tarefa ou restringir o ambiente a ramos específicos. Você também pode criar e implementar regras de proteção personalizadas alimentadas pelos Aplicativos do GitHub para usar sistemas de 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 essa regra para exigir que uma pessoa ou equipe específica aprove trabalhos de fluxo de trabalho que fazem 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 autoavaliações 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 permitir revisões coletivas, garante-se que mais de uma pessoa revise as implantações em ambientes protegidos.

  Para obter mais informações sobre como examinar trabalhos que fazem referência a um ambiente com revisores necessários, consulte Implantações de Revisão.

• Regras de projeção do temporizador de espera. Você pode usar uma regra de proteção de temporizador de espera para atrasar um trabalho por um período específico após o trabalho ser disparado inicialmente antes que a implantação do ambiente continue. O tempo (em minutos) deve ser um 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 branch e tag. Você pode usar regras de proteção de branch e tag de implantação para restringir quais branches e tags são usados para implantação no ambiente. Você tem várias opções para regras de proteção de marca e branch de implantação para um ambiente.

  • Nenhuma restrição estabelece nenhuma limitação sobre qual ramificação ou tag pode ser implantada no ambiente.
  • Apenas branches protegidos permitem somente branches com regras de proteção habilitadas para implantação no ambiente. Se nenhuma regra de proteção de branch for definida para qualquer branch no repositório, todos os branches poderão ser implantados. A configuração de branches e tags selecionadas garante que somente branches e tags que correspondam aos padrões de nome que você especificou possam ser implantados no ambiente.
  • Se você especificar releases/* como uma regra de branch de tag de implantação, somente um branch ou uma tag com um nome que começa com releases/ pode ser implantado no ambiente. (Caracteres curinga não corresponderão a /. Para fazer a correspondência de branches ou tags que começam com release/ e que contêm outra barra "/" única, use release/*/*.) Se você adicionar main como uma regra de branch, um branch chamado main também poderá ser implantado no ambiente.

• Regras de proteção de implantação personalizadas. Você pode criar regras de proteção personalizadas para bloquear implantações para usar serviços de parceiro. 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 preparaçã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ê poderá 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 snippets de fluxo de trabalho anteriores, a palavra-chave run é usada para imprimir uma cadeia de caracteres de texto. Como a palavra-chave run instrui o trabalho a executar um comando no executor, você usa a palavra-chave run para executar ações ou scripts.

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

Neste exemplo, você usa o npm para instalar o bats pacote de teste de 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 diretório .github/scripts/ e, em seguida, fornecer o caminho e o tipo de shell usando a palavra-chave run.

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