Contextos

Sobre os contextos

Os contextos são uma forma de acessar informações sobre execuções de fluxo de trabalho, ambientes dos executores, trabalhos e etapas. Cada contexto é um objeto que contém propriedades, que podem ser strings ou outros objetos.

Os contextos, objetos e propriedades variarão significativamente em diferentes condições de execução do fluxo de trabalho. Por exemplo, o contexto matriz só é povoado para trabalhos em uma matrizmatriz.

Você pode acessar contextos usando a sintaxe da expressão. Para obter mais informações, consulte "Expressões".

${{ <context> }}

Como parte de uma expressão, você pode acessar informações de contexto usando uma das duas sintaxes.

• Sintaxe de índice: github['sha'];
• Sintaxe de propriedade de desreferência: github.sha

Para usar a sintaxe de dereferência da propriedade, o nome da propriedade deve começar com uma letra ou _ e conter apenas caracteres alfanuméricos, - ou _.

Se você tentar desfazer uma propriedade inexistente, isso irá retornar uma string vazia.

Determinar quando usar contextos

GitHub Actions inclui uma coleção de variáveis denominadas contextos e uma coleção similar de variáveis denominadas variáveis de ambiente padrão. Estas variáveis são destinadas a serem usadas em diferentes pontos do fluxo de trabalho:

• Variáveis de ambiente padrão: Essas variáveis existem apenas no executor que está executando seu trabalho. Para obter mais informações, consulte "Variáveis de ambiente padrão".
• Contextos: Você pode usar a maioria dos contextos em qualquer ponto do seu fluxo de trabalho, incluindo quando as variáveis de ambiente padrão estariam indisponíveis. Por exemplo, você pode usar contextos com expressões para realizar o processamento inicial antes que o trabalho seja encaminhado para um executor para execução. Isso permite que você use um contexto com a palavra-chave condicional if para determinar se uma etapa deve ser executada. Assim que o trabalho estiver em execução, você também poderá recuperar as variáveis de contexto do executor que está executando o trabalho, como runner.os. Para obter informações sobre onde você pode usar vários contextos dentro de um fluxo de trabalho, consulte "Disponibilidade de contexto".

O exemplo a seguir demonstra como esses diferentes tipos de variáveis de ambiente podem ser usados juntos em um trabalho:

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"

Neste exemplo, o comando if verifica o github.ref para determinar o nome do branch atual. Se o nome for refs/heads/main, as etapas subsequentes serão executadas. A verificação if é processada por GitHub Actions, e o trabalho é enviado apenas para o executor se o resultado for verdadeiro. Assim que o trabalho é enviado para o executor, a etapa é executada e refere-se �  variável de ambiente $GITHUB_REF do executor.

Disponibilidade do contexto

Contextos diferentes estão disponíveis durante a execução de um fluxo de trabalho. Por exemplo, o contexto de segredos só pode ser usado em certos lugares dentro de um trabalho.

Além disso, algumas funções só podem ser utilizadas em determinados lugares. Por exemplo, a função hashFiles não está disponível em qualquer lugar.

A tabela a seguir indica onde cada contexto e função especial pode ser utilizado dentro de um fluxo de trabalho. A menos que esteja listado abaixo, uma função pode ser usada em qualquer lugar. | | Caminho | Contexto | Funções especiais | | --------------------------- | --------------------------- | --------------------------- | | concorrência | github | | | env | github, secrets | | | jobs.<job_id>.concurrency | github, needs, strategy, matrix | | | jobs.<job_id>.container | github, needs, strategy, matrix | | | jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets | | | jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | | | jobs.<job_id>.continue-on-error | github, needs, strategy, matrix | | | jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env | | | jobs.<job_id>.env | github, needs, strategy, matrix, secrets | | | jobs.<job_id>.environment | github, needs, strategy, matrix | | | jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps | | | jobs.<job_id>.if | github, needs | always, cancelled, success, failure | | jobs.<job_id>.name | github, needs, strategy, matrix | | | jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps | | | jobs.<job_id>.runs-on | github, needs, strategy, matrix | | | jobs.<job_id>.services | github, needs, strategy, matrix | | | jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets | | | jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | | | jobs.<job_id>.steps.continue-on-error | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.env | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps | always, cancelled, success, failure, hashFiles | | jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.timeout-minutes | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.with | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | | jobs.<job_id>.strategy | github, needs | | | jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix | |

Exemplo: imprimir informações de contexto no registro

Você pode imprimir o conteúdo de contextos no registro para depuração. A função toJSON é necessária para imprimir objetos do JSON no registro.

name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        id: github_context_step
        run: echo '${{ toJSON(github) }}'
      - name: Dump job context
        run: echo '${{ toJSON(job) }}'
      - name: Dump steps context
        run: echo '${{ toJSON(steps) }}'
      - name: Dump runner context
        run: echo '${{ toJSON(runner) }}'
      - name: Dump strategy context
        run: echo '${{ toJSON(strategy) }}'
      - name: Dump matrix context
        run: echo '${{ toJSON(matrix) }}'

Contexto github

O contexto github context contém informações sobre a execução do fluxo de trabalho e sobre o evento que a acionou. Você também pode ler a maioria dos dados do github em variáveis de ambiente. Para obter mais informações sobre as variáveis de ambiente, consulte "Usando variáveis de ambiente".

Exemplo de conteúdo do contexto github

O contexto a seguir é de um fluxo de trabalho executado pelo evento push. O objeto evento neste exemplo foi truncado porque é idêntico ao conteúdo da carga do webhook de push.

{
  "token": "***",
  "job": "dump_contexts_to_log",
  "ref": "refs/heads/my_branch",
  "sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369",
  "repository": "octocat/hello-world",
  "repository_owner": "octocat",
  "repositoryUrl": "git://github.com/octocat/hello-world.git",
  "run_id": "1536140711",
  "run_number": "314",
  "retention_days": "90",
  "run_attempt": "1",
  "actor": "octocat",
  "workflow": "Context testing",
  "head_ref": "",
  "base_ref": "",
  "event_name": "push",
  "event": {
    ...
  },
  "server_url": "https://github.com",
  "api_url": "https://api.github.com",
  "graphql_url": "https://api.github.com/graphql",
  "ref_name": "my_branch",
  "ref_protected": false,
  "ref_type": "branch",
  "secret_source": "Actions",
  "workspace": "/home/runner/work/hello-world/hello-world",
  "action": "github_step",
  "event_path": "/home/runner/work/_temp/_github_workflow/event.json",
  "action_repository": "",
  "action_ref": "",
  "path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602",
  "env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602"
}

Exemplo de uso do contexto github

Este fluxo de trabalho de exemplo usa o contexto github.event_name para executar um trabalho somente se a execução do fluxo de trabalho for acionada pelo evento pull_request.

name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run normal CI
        run: ./run-tests

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - uses: actions/checkout@v2
      - name: Run PR CI
        run: ./run-additional-pr-ci

Contexto env

O contexto env contém variáveis de ambiente que foram definidas em um fluxo de trabalho, trabalho ou etapa. Para obter mais informações sobre como configurar variáveis de ambiente em seu fluxo de trabalho, consulte "Sintaxe do fluxo de trabalho para GitHub Actions".

A sintaxe de contexto env permite que você use o valor de uma variável de ambiente no seu arquivo de fluxo de trabalho. Você pode usar o contexto env no valor de qualquer chave em uma etapa, exceto para as chaves id e uses. Para obter mais informações sobre a sintaxe da etapa, consulte "Sintaxe do fluxo de trabalho para o GitHub Actions".

Se você desejar 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.

Conteúdo do exemplo do contexto env

O conteúdo do contexto env é um mapeamento de nomes de variáveis de ambiente com os seus valores. O conteúdo do contexto pode mudar dependendo de onde é usado na execução do fluxo de trabalho.

{
  "first_name": "Mona",
  "super_duper_var": "totally_awesome"
}

Exemplo de uso do contexto env

Este exemplo de fluxo de trabalho mostra como o contexto env pode ser configurado no fluxo de trabalho, níveis de trabalho e de etapas, bem como usar o contexto em etapas.

Quando mais de uma variável de ambiente é definida com o mesmo nome, GitHub usa a variável de ambiente mais específica. Por exemplo, uma variável de ambiente definida em uma etapa substituirá variáveis de trabalho e de fluxo de trabalho pelo mesmo nome enquanto a etapa é executada. Uma variável definida para um trabalho substituirá uma variável de fluxo de trabalho com o mesmo nome, enquanto o trabalho é executado.

name: Hi Mascot
on: push
env:
  mascot: Mona
  super_duper_var: totally_awesome

jobs:
  windows_job:
    runs-on: windows-latest
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Mona
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Octocat
        env:
          mascot: Octocat
  linux_job:
    runs-on: ubuntu-latest
    env:
      mascot: Tux
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Tux

Contexto trabalho

O contexto job (trabalho) contém informações sobre o trabalho atualmente em execução.

Exemplo de conteúdo do contexto trabalho

Este exemplo contexto do job usa um contêiner de serviço do PostgreSQL com portas mapeadas. Se não houver contêineres ou contêineres de serviço usados em um trabalho, o contexto trabalho só conterá a propriedade status.

{
  "status": "success",
  "container": {
    "network": "github_network_53269bd575974817b43f4733536b200c"
  },
  "services": {
    "postgres": {
      "id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
      "ports": {
        "5432": "49153"
      },
      "network": "github_network_53269bd575974817b43f4733536b200c"
    }
  }
}

Exemplo de uso do contexto trabalho

Este exemplo de fluxo de trabalho configura um contêiner de serviço do PostgreSQL e mapeia automaticamente a porta 5432 do recipiente de serviço com uma porta disponível escolhida aleatoriamente no host. O contexto job é usado para acessar o número da porta atribuída no host.

name: PostgreSQL Service Example
on: push
jobs:
  postgres-job:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
          - 5432

    steps:
      - uses: actions/checkout@v2
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: ./run-tests

Contexto etapas

O contexto etapas contém informações sobre as etapas do trabalho atual que possuem um id especificado e já executado.

Exemplo de conteúdo do contexto etapas

Este exemplo passo contexto mostra duas etapas anteriores que tinham um id especificado. O id da primeira etapa era denominado checkout e o segundo, generate_number. A etapa generate_number tinha uma saída denominada random_number.

{
  "checkout": {
    "outputs": {},
    "outcome": "success",
    "conclusion": "success"
  },
  "generate_number": {
    "outputs": {
      "random_number": "1"
    },
    "outcome": "success",
    "conclusion": "success"
  }
}

Exemplo de uso do contexto de etapas

Este exemplo de fluxo de trabalho gera um número aleatório como saída em uma etapa e uma etapa posterior usa o contexto etapas para ler o valor dessa saída.

name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - id: checkout
        uses: actions/checkout@v2
      - name: Generate 0 or 1
        id: generate_number
        run:  echo "::set-output name=random_number::$(($RANDOM % 2))"
      - name: Pass or fail
        run: |
          if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi

Contexto do executor

O contexto do executor contém informações sobre o executor que está executando o trabalho atual.

Exemplo de conteúdo do contexto do executor

O contexto de exemplo a seguir é de um executor do Linux hospedado em GitHub.

{
  "os": "Linux",
  "arch": "X64",
  "name": "GitHub Actions 2",
  "tool_cache": "/opt/hostedtoolcache",
  "temp": "/home/runner/work/_temp"
}

Exemplo de uso do contexto do contexto do executor

Este exemplo de fluxo de trabalho usa o contexto executor para definir o caminho para o diretório temporário e gravar registros e se, o fluxo de trabalho falhar, ele irá fazer o uplad dos registros como artefatos.

name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          ./build.sh --log-path ${{ runner.temp }}/build_logs
      - name: Upload logs on fail
        if: ${{ failure() }}
        uses: actions/upload-artifact@v2
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

contexto segredos

O contexto segredos contém os nomes e valores de segredos disponíveis para a execução de um fluxo de trabalho. O contexto segredos não está disponível para ações compostas. Para obter mais informações sobre segredos, consulte "Segredos criptografados".

GITHUB_TOKEN é um segredo que é criado automaticamente para cada execução de fluxo de trabalho, e é sempre incluído no contexto segredos. Para obter mais informações, consulte "Autenticação automática de tokens".

Exemplo de conteúdo do contexto segredo

O conteúdo de exemplo do contexto dos segredos mostra o GITHUB_TOKEN automático, assim como outros dois segredos disponíveis para a execução do fluxo de trabalho.

{
  "github_token": "***",
  "NPM_TOKEN": "***",
  "SUPERSECRET": "***"
}

Exemplo de uso do contexto dos segredos

Este exemplo de fluxo de trabalho usa a ação etiquetadora, que exige o GITHUB_TOKEN como o valor para o parâmetro de entrada do token:

name: Pull request labeler
on: [ pull_request_target ]

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v3
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Contexto estratégia

Para fluxos de trabalho com uma matriz, o contexto estratégia contém informações sobre a estratégia de execução da matriz para o trabalho atual.

Exemplo de conteúdo do contexto estratégia

O conteúdo de exemplo a seguir do contexto estratégia é de uma matriz com quatro trabalhos, e é tirada do trabalho final. Observe a diferença entre o número de job-index baseado em zero e o total de job-job que não é baseado em zero.

{
  "fail-fast": true,
  "job-index": 3,
  "job-total": 4,
  "max-parallel": 4
}

Exemplo de uso do contexto estratégia

Esse exemplo de fluxo de trabalho usa a propriedade strategy.job-index para definir um nome exclusivo para um arquivo de registro para cada trabalho em uma matriz.

name: Test matrix
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v2
      - run: npm test > test-job-${{ strategy.job-index }}.txt
      - name: Upload logs
        uses: actions/upload-artifact@v2
        with:
          name: Build log for job ${{ strategy.job-index }}
          path: test-job-${{ strategy.job-index }}.txt

Contexto matriz

Para fluxos de trabalho com uma matriz, o contexto matriz contém as propriedades definidas no arquivo do fluxo de trabalho que se aplicam ao trabalho atual. Por exemplo, se você configurar uma matriz com as chaves os e nó, o objeto do contexto matriz irá incluir as propriedades os e nó com os valores usados para o trabalho atual.

Não há propriedades padrão no contexto matriz, apenas as que são definidas no arquivo do fluxo de trabalho.

Exemplo de conteúdo do contexto matriz

O exemplo a seguir do contexto matriz é de um trabalho em uma matriz que tem as propriedades de matriz os e nó definidas no fluxo de trabalho. O trabalho está executando a combinação matriz de um ubuntu-latest OS e do Node.js versão 16.

{
  "os": "ubuntu-latest",
  "node": 16
}

Exemplo de uso do contexto matriz

Este exemplo de fluxo de trabalho cria uma matriz com as chaves os e nós. Ele usa a propriedade matriz.os para definir o tipo de executor para cada trabalho e usa a propriedade matrix.node para definir a versão do Node.js para cada trabalho.

name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

Contexto needs

O contexto needs contém saídas de todos os trabalhos definidos como uma dependência do trabalho atual. Para obter mais informações sobre a definição de dependências de trabalho, consulte "Sintaxe de fluxo de trabalho para GitHub Actions".

Exemplo de conteúdo do contexto needs

O conteúdo de exemplo a seguir do contexto needs mostra informações para dois trabalhos dos quais o trabalho atual depende.

{
  "build": {
    "result": "success",
    "outputs": {
      "build_id": "ABC123"
    }
  },
  "deploy": {
    "result": "failure",
    "outputs": {}
  }
}

Exemplo de uso do contexto needs

Esse exemplo do fluxo de trabalho tem três trabalhos: um trabalho de criação que faz a criação, um trabalho de implantação que exige o trabalho de criação e um trabalho de depuração que exige os trabalhos de criação e implantação e que é executado apenas se houver uma falha no fluxo de trabalho. O trabalho de implantação também usa o contexto needs para acessar uma saída do trabalho de criação.

name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - uses: actions/checkout@v2
      - name: Build
        id: build_step
        run: |
          ./build
          echo "::set-output name=build_id::$BUILD_ID" 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: ./deploy --build ${{ needs.build.outputs.build_id }}
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - uses: actions/checkout@v2
      - run: ./debug