Variáveis de ambiente

Sobre as variáveis de ambiente

Você pode usar variáveis de ambiente para armazenar informações que você deseja referenciar no seu fluxo de trabalho. Você faz referência a variáveis de ambiente em uma etapa do fluxo de trabalho ou uma ação, e as variáveis são interpoladas na máquina do executor que executa seu fluxo de trabalho. Os comandos que são executados em ações ou etapas do fluxo de trabalho podem criar, ler e modificar variáveis de ambiente.

Você pode definir as suas próprias variáveis de ambiente personalizadas, você pode usar as variáveis de ambiente padrão que GitHub define automaticamente, e você também pode usar qualquer outra variável de ambiente que seja definida no ambiente de trabalho no executor. As variáveis de ambiente diferenciam entre maiúsculas e minúsculas.

Para definir uma variável de ambiente personalizada, você deverá defini-la no arquivo do fluxo de trabalho. O escopo de uma variável de ambiente personalizada está limitado ao elemento em que ele está definido. Você pode definir variáveis de ambiente cujos escopos são definidos para:

• Todo o fluxo de trabalho, usando env no nível superior do arquivo de fluxo de trabalho.
• O conteúdo de um trabalho dentro de um fluxo de trabalho, usando jobs.<job_id>.env.
• Uma etapa específica em um trabalho, usando jobs.<job_id>.steps[*].env.

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

O exemplo acima mostra três variáveis de ambiente personalizadas sendo usadas em um comando de eco: $DAY_OF_WEEK, $Greeting e $First_Name. Os valores e os escopos para essas variáveis de ambiente são definidos no fluxo de trabalho, no trabalho e na etapa respectivamente.

Porque interpolação de variável de ambiente é feita depois que um trabalho do fluxo de trabalho é enviado para a máquina de um executor, você deve usar a sintaxe apropriada para o shell que é usado no executor. Neste exemplo, o fluxo de trabalho especifica ubuntu-latest. Por padrão, os executores do Linux usam o shell de bash. Portanto, você deve usar a sintaxe $NAME. Se o fluxo de trabalho especificou um executor do Windows, você usaria a sintaxe do PowerShell, $env:NAME. Para obter mais informações sobre shells, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Usando contextos para acessar valores da variável de ambiente

Além das variáveis de ambiente, GitHub Actions também permite que você defina e leia valores que usam contextos. As variáveis e os contextos do ambiente são destinados a serem usados em diferentes pontos do fluxo de trabalho.

As variáveis de ambiente são sempre interpoladas no executor de máquina virtual. No entanto, as partes de um fluxo de trabalho são processadas por GitHub Actions e não são enviadas para o executor. Não é possível usar variáveis de ambiente nessas partes de um arquivo de fluxo de trabalho. Em vez disso, pode-se utilizar contextos. Por exemplo, uma condicional se, que determina se um trabalho ou etapa é enviado para o executor, sempre será processada por GitHub Actions. Você pode usar um contexto na afirmação de uma condicional se para acessar o valor de uma variável de ambiente.

env:
  DAY_OF_WEEK: Monday

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

Nessa modificação do primeiro exemplo, introduzimos uma condicional se. A etapa do fluxo de trabalho agora só é executada se DAYS_OF_WEEK estiver definido como "Segunda-feira". Nós acessamos este valor a partir da afirmação condicional se usando o contexto env.

Você usará comumente o contexto env ou github para acessar os valores das variáveis de ambiente em partes do fluxo de trabalho que são processadas antes que os trabalhos sejam enviadas para os executores.

Contexto	Caso de uso	Exemplo
env	Variáveis de ambiente personalizado de referência definidas no fluxo de trabalho.	${{ env.MY_VARIABLE }}
github	Informações de referência sobre a execução do fluxo de trabalho e o evento que acionou a execução.	${{ github.repository }}

Há muitos outros contextos que você pode usar para uma série de finalidades nos seus fluxos de trabalho. Para obter mais informações, consulte "Contextos". Para obter mais informações sobre onde você pode usar contextos específicos dentro de um fluxo de trabalho, consulte "Disponibilidade de Contexto".

Outros tipos de variáveis

Na maioria dos lugares em um fluxo de trabalho, os únicos tipos de variáveis que você pode usar são variáveis de ambiente, como $MY_VARIABLE, ou a propriedade de contexto equivalente como, por exemplo, ${{ env.MY_VARIABLE }}. Exceções:

• Entradas para os eventos workflow_call e workflow_despatch que permitem que você passe valores para um fluxo de trabalho. Para obter mais informações, consulte on.workflow_call.inputs e on.workflow_dispatch.inputs.
• Saídas de trabalhos, que permitem passar valores entre trabalhos em um fluxo de trabalho. Para obter mais informações, consulte trabalhos.<job_id>.outputs.
• As variáveis em uma expressão de formato, que permite que você substitua partes de uma string. Para obter mais informações, consulte formato.

Convenções de nomenclatura para variáveis de ambiente

Ao definir uma variável de ambiente personalizada, você não pode usar nenhum dos nomes das variáveis de ambiente padrão. Para obter uma lista completa destas, consulte "variáveis de ambiente padrão" abaixo. Se você tentar substituir o valor de uma dessas variáveis de ambiente padrão, a atribuição será ignorada.

Qualquer variável de ambiente nova que você definir e apontar para um local no sistema de arquivos deve ter um sufixo _PATH. As variáveis de ambiente padrão HOME, GITHUB_ENV e GITHUB_WORKSPACE são exceções a essa convenção.

Variáveis padrão de ambiente

As variáveis de ambiente padrão que os conjuntos de GitHub estão disponíveis para cada etapa de um fluxo de trabalho.

É altamente recomendável que as ações usem as variáveis do ambiente para acessar o sistema do arquivo em vez de usar os caminhos do arquivo com codificação rígida. GitHub define as variáveis de ambiente para ações a serem usadas em todos os ambientes executores.

Variável de ambiente	Descrição
CI	Definido sempre como verdadeiro.
GITHUB_ACTION	O nome da ação atualmente em execução ou o id de uma etapa. Por exemplo, para uma ação, __repo-owner_name-of-action-repo. GitHub remove caracteres especiais e usa o nome __executar quando a etapa atual executa um script sem um id. Se você usar o mesmo script ou ação mais de uma vez no mesmo trabalho, o nome incluirá um sufixo que consiste do número de sequência precedido por um sublinhado. Por exemplo, o primeiro script que você executar terá o nome __run e o segundo script será denominado __run_2. Da mesma forma, a segunda invocação de actions/checkout será actionscheckout2.
GITHUB_ACTION_PATH	O caminho onde uma ação está localizada. Esta propriedade só é compatível com ações compostas. Você pode usar este caminho para acessar arquivos localizados no mesmo repositório da ação. Por exemplo, /home/runner/work/_actions/repo-owner/name-of-action-repo/v1.
GITHUB_ACTION_REPOSITORY	Para uma etpa que executa uma ação, este é o nome do proprietário e do repositório da ação. Por exemplo, actions/checkout.
GITHUB_ACTIONS	Definido sempre como verdadeiro quando GitHub Actions estiver executando o fluxo de trabalho. Você pode usar esta variável para diferenciar quando os testes estão sendo executados localmente ou por GitHub Actions.
GITHUB_ACTOR	Nome da pessoa ou aplicativo que iniciou o fluxo de trabalho. Por exemplo, octocat.
GITHUB_API_URL	Retorna a URL da API. Por exemplo: http(s)://[hostname]/api/v3.
GITHUB_BASE_REF	O nome do ref da base ou o branch de destino do pull request na execução de um fluxo de trabalho. Isso só é definido quando o evento que aciona a execução de um fluxo de trabalho é pull_request ou pull_request_target. Por exemplo, principal.
GITHUB_ENV	Caminho no executor para o arquivo que define variáveis de ambiente dos comandos do fluxo de trabalho. Este arquivo é único para a etapa atual e alterações para cada etapa de um trabalho. Por exemplo, /home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a. Para obter mais informações, consulte "Comandos do fluxo de trabalho para GitHub Actions".
GITHUB_EVENT_NAME	Nome do evento que acionou a execução do fluxo de trabalho. Por exemplo, workflow_despatch.
GITHUB_EVENT_PATH	O caminho para o arquivo no executor que contém a carga completa do webhook do evento. Por exemplo, /github/workflow/event.json.
GITHUB_GRAPHQL_URL	Retorna a URL API do GraphQL. Por exemplo: http(s)://[hostname]/api/graphql.
GITHUB_HEAD_REF	A ref principal ou o branch da fonte do pull request na execução de um fluxo de trabalho. Esta propriedade só é definida quando o evento que aciona a execução de um fluxo de trabalho for pull_request ou pull_request_target. Por exemplo, feature-branch-1.
GITHUB_JOB	O job_id do trabalho atual. Por exemplo, greeting_job.
GITHUB_PATH	O caminho no executor para o arquivo que define as variáveis do sistema PATH a partir de comandos do fluxo de trabalho. Este arquivo é único para a etapa atual e alterações para cada etapa de um trabalho. Por exemplo, /home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5. Para obter mais informações, consulte "Comandos do fluxo de trabalho para GitHub Actions."
GITHUB_REF	Branch ou ref tag que acionou a execução do fluxo de trabalho. Para branches, este é o formato refs/heads/<branch_name>, para tags é refs/tags/<tag_name>, e para pull requests é refs/pull/<pr_number>/merge. Esta variável só é definida se um branch ou tag estiver disponível para o tipo de evento. Por exemplo, refs/heads/feature-branch-1.
GITHUB_REPOSITORY	O nome do proprietário e do repositório. Por exemplo, octocat/Hello-World.
RUNNER_NAME	O nome do executor que executa a tarefa. Por exemplo, Hosted Agent
RUNNER_TOOL_CACHE	O caminho para o diretório que contém ferramentas pré-instaladas para executores hospedados em GitHub. For more information, see "About GitHub-hosted runners". For example, C:\hostedtoolcache\windows

Detectando o sistema operacional

Você pode escrever um único arquivo de fluxo de trabalho que pode ser usado para sistemas operacionais diferentes usando a variável de ambiente padrão RUNNER_OS e a propriedade de contexto correspondente ${{ runner.os }}. Por exemplo, o seguinte fluxo de trabalho poderia ser executado com sucesso se você alterasse o sistema operacional de macos-latest para windows-latest sem precisar alterar a sintaxe das variáveis de ambiente, que difere dependendo do shell que está sendo usado pelo executor.

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."

Neste exemplo, as duas afirmações se verificam a propriedade os do contexto executor para determinar o sistema operacional do executor. As condicionais se são processadas por GitHub Actions, e apenas as etapas onde a verificação resolve como verdadeiro são enviadas para o executor. Aqui, uma das verificações será sempre verdadeira e a outra falsa. Portanto, apenas uma dessas etapas será enviada para o executor. Assim que o trabalho for enviado para o executor, a etapa será executada e a variável de ambiente no comando echo será interpolada usando a sintaxe apropriada ($env:NAME para o PowerShell no Windows e $NAME para o bash e sh no Linux e MacOS). Neste exemplo, a instrução runs-on: macos-latest significa que a segunda etapa será executada.

Passando valores entre etapas e trabalhos em um fluxo de trabalho

Se você gerar um valor em uma etapa de um trabalho, você poderá usar o valor em etapas subsequentes do mesmo trabalho, atribuindo o valor para uma variável de ambiente existente ou nova e, em seguida, gravando-o no arquivo de ambiente GITHUB_ENV. O arquivo de ambiente pode ser usado diretamente por uma ação ou de um comando shell no arquivo do fluxo de trabalho usando a palavra-chave executar. Para obter mais informações, consulte "Comandos do fluxo de trabalho para GitHub Actions".

Se você deseja passar um valor de uma etapa de um trabalho em um fluxo de trabalho para uma etapa de outro trabalho no fluxo de trabalho, você poderá definir o valor como uma saída de trabalho. Em seguida, você poderá fazer referência a saída desse trabalho a partir de uma etapa em outro trabalho. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".