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

Observação: Você pode listar todo o conjunto de variáveis de ambiente que estão disponíveis para uma etapa de fluxo de trabalho usando run: env em uma etapa e depois examinando a saída para a etapa.

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.

Observação: De modo geral, os contextos são indicados usando o sinal de dólar e chaves, como ${{ context.property }}. Em uma condicional se, os ${{ e }} são opcionais, mas se você usá-los, eles deverão incluir toda a instrução de comparação, conforme mostrado acima.

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: `https://[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: `https://[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`.
`GITHUB_WORKFLOW`	O nome do fluxo de trabalho. Por exemplo, `My test workflow`. Se o fluxo de trabalho não determinar um `nome`, o valor desta variável será o caminho completo do arquivo do fluxo de trabalho no repositório.
`RUNNER_NAME`	O nome do executor que executa a tarefa. Por exemplo, `Hosted Agent`

Observação:

Se você precisar usar o URL de uma execução do fluxo de trabalho em um trabalho, você poderá combinar estas variáveis de ambiente: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
A maioria das variáveis de ambiente padrão tem uma propriedade de contexto correspondente e igualmente nomeada. Por exemplo, o valor da variável ambiente GITHUB_REF pode ser lido durante o processamento do fluxo de trabalho usando a propriedade do contexto ${{ github.ref }}.

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