Контексты

Сведения о контекстах

Контексты — это способ доступа к сведениям о выполнении рабочих процессов, переменных, средах средств выполнения, заданиях и шагах. Каждый контекст — это объект, содержащий свойства, которые могут быть строками или другими объектами.

Контексты, объекты и свойства во многом зависят от условий выполнения рабочего процесса. Например, контекст matrix заполняется только для заданий в матрице.

Обращаться к контекстам можно с помощью синтаксиса выражений. Дополнительные сведения см. в разделе Выражения.

${{ <context> }}

В выражении доступ к данным контекста можно получить с помощью одного из двух видов синтаксиса.

• Синтаксис индексов: github['sha']
• Синтаксис разыменования свойств: github.sha

Чтобы использовать синтаксис разыменования свойств, имя свойства должно начинаться с буквы или _ и содержать только буквенно-цифровые символы, - или _.

Если попытаться разыменовать несуществующее свойство, оно будет вычислено как пустая строка.

Когда используются контексты

GitHub Actions включает коллекцию переменных , называемых контекстами , и аналогичную коллекцию переменных, называемых переменными по умолчанию. Эти переменные предназначены для использования в разных точках рабочего процесса:

• Переменные среды по умолчанию: Эти переменные среды существуют только в средстве выполнения, которое выполняет задание. Дополнительные сведения см. в разделе Переменные.
• Контекстах: Вы можете использовать большинство контекстов в любой момент рабочего процесса, в том числе когда переменные по умолчанию будут недоступны. Например, можно использовать контексты с выражениями для выполнения начальной обработки перед маршрутизацией задания в средство выполнения тестов. Это позволяет использовать контекст с условным ключевым словом if, чтобы определить, следует ли выполнять шаг. После выполнения задания можно также извлечь переменные контекста из средства выполнения тестов, которое выполняет задание, например runner.os. Дополнительные сведения о том, где можно использовать различные контексты в рабочем процессе, см. в разделе Контексты.

В следующем примере показано, как эти различные типы переменных можно использовать вместе в задании:

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"

В этом примере инструкция if проверяет контекст github.ref, чтобы определить имя текущей ветви; если используется имя refs/heads/main, то выполняются последующие шаги. Проверка if обрабатывается GitHub Actions, и задание отправляется в средство выполнения тестов только в том случае, если результат равен true. После отправки задания средству выполнения выполняется шаг, который ссылается на $GITHUB_REF переменную из средства выполнения.

Доступность контекста

В экземпляре рабочего процесса доступны различные контексты. Например, контекст secrets может использоваться только в определенных местах задания.

Кроме того, некоторые функции также могут использоваться только в определенных местах. Например, функция hashFiles доступна не везде.

В следующей таблице показано, где в рабочем процессе можно использовать каждый контекст и специальную функцию. Если эти сведения не приводятся, значит функцию можно использовать где угодно.

| Ключ рабочего процесса | Контекст | Специальные функции | | ---- | ------- | ----------------- | | concurrency | github, inputs | Нет | | env | github, secrets, inputs | Нет | | jobs.<job_id>.concurrency | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.container | github, needs, strategy, matrix, env, secrets, inputs | Нет | | jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets, inputs | Нет | | jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets, inputs | Нет | | jobs.<job_id>.continue-on-error | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env, inputs | Нет | | jobs.<job_id>.env | github, needs, strategy, matrix, secrets, inputs | Нет | | jobs.<job_id>.environment | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps, inputs | Нет | | jobs.<job_id>.if | github, needs, inputs | always, cancelled, success, failure | | jobs.<job_id>.name | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | Нет | | jobs.<job_id>.runs-on | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.secrets.<secrets_id> | github, needs, secrets | Нет | | jobs.<job_id>.services | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets, inputs | Нет | | jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets, inputs | Нет | | jobs.<job_id>.steps.continue-on-error | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.env | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps, inputs | always, cancelled, success, failure, hashFiles | | jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.timeout-minutes | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.with | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.strategy | github, needs, inputs | Нет | | jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix, inputs | Нет | | jobs.<job_id>.with.<with_id> | github, needs | Нет | | on.workflow_call.inputs.<inputs_id>.default | github | Нет | | on.workflow_call.outputs.<output_id>.value | github, jobs, inputs | Нет |

Пример: вывод данных контекста в журнал

Содержимое контекстов можно выводить в журнал для отладки. Для вывода объектов JSON в журнал в правильном формате требуется функция toJSON.

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) }}'

Контекст github

Контекст github содержит сведения об экземпляре рабочего процесса и событии, которое запустило этот экземпляр. Большую часть данных контекста github можно прочитать в переменных среды. Дополнительные сведения о переменных среды см. в разделе Переменные.

Пример содержимого контекста github

Следующий пример контекста взят из экземпляра рабочего процесса, запущенного событием push. В этом примере объект event усечен, так как он идентичен полезным данным веб-перехватчика 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"
}

Пример использования контекста github

В этом примере задание выполняется с помощью контекста github.event_name, только если экземпляр рабочего процесса был запущен событием pull_request.

name: Run CI
on: [push, pull_request]

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

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

Контекст env

Контекст env содержит переменные, заданные в рабочем процессе, задании или шаге. Дополнительные сведения о настройке переменных в рабочем процессе см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Синтаксис env контекста позволяет использовать значение переменной в файле рабочего процесса. Контекст env можно использовать в значении любого ключа в шаге кроме id и uses. Дополнительные сведения о синтаксисе шага см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Если вы хотите использовать значение переменной внутри средства выполнения, используйте обычный метод операционной системы средства выполнения для чтения переменных среды.

Пример содержимого контекста env

Содержимое контекста env представляет собой сопоставление имен переменных со значениями. Содержимое контекста зависит от места, где он используется в экземпляре рабочего процесса.

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

Пример использования контекста env

В этом примере рабочего процесса показано, как настроить контекст env на уровне рабочего процесса, задания и шага, а также как использовать контекст в шагах.

Если определено несколько переменных среды с одинаковыми именами, GitHub использует наиболее конкретную переменную. Например, переменная среды, определенная в шаге, будет переопределять переменные среды задания и рабочего процесса с тем же именем, пока выполняется шаг. Переменная среды, определенная для задания, переопределяет переменную рабочего процесса с тем же именем, в то время как задание выполняется.

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

Контекст job

Контекст job содержит сведения о выполняемом в данный момент задании.

Пример содержимого контекста job

В этом примере контекста job используется контейнер службы PostgreSQL с сопоставленными портами. Если в задании не используются контейнеры или контейнеры служб, контекст job содержит только свойство status.

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

Пример использования контекста job

В этом примере рабочего процесса настраивается контейнер службы PostgreSQL и порт 5432 в контейнере службы автоматически сопоставляется со случайным выбранным доступным портом на узле. Контекст job используется для получения номера порта, назначенного на узле.

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@v3
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: ./run-tests

Контекст jobs

Контекст jobs доступен только в повторно используемых рабочих процессах и может использоваться только для задания выходных данных для повторно используемого рабочего процесса. Дополнительные сведения см. в разделе Повторное использование рабочих процессов.

Пример содержимого контекста jobs

Этот пример контекста jobs содержит результат и выходные данные задания из повторно используемых рабочих процессов.

{
  "example_job": {
    "result": "success",
    "outputs": {
      "output1": "hello",
      "output2": "world"
    }
  }
}

Пример использования контекста jobs

В этом примере повторно используемый рабочий процесс использует контекст jobs для задания выходных данных для повторно используемого рабочего процесса. Обратите внимание, как выходные данные передаются из шагов в задание, а затем в триггер workflow_call. Дополнительные сведения см. в разделе Повторное использование рабочих процессов.

name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

Контекст steps

В контексте steps содержатся сведения об уже запущенных шагах в текущем задании с указанным свойством id.

Пример содержимого контекста steps

В этом примере контекста steps показаны два предыдущих шага с заданным свойством id. У первого шага свойство id называлось checkout, у второго — generate_number. Выходными данными шага generate_number был номер random_number.

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

Пример использования контекста steps

В этом примере рабочего процесса в качестве выходных данных одного шага создается случайное число, а на последующем шаге эти выходные данные считываются с помощью контекста steps.

name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - id: checkout
        uses: actions/checkout@v3
      - 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

Контекст runner

Контекст runner содержит сведения о средстве выполнения, которое запускает текущее задание.

Пример содержимого контекста runner

Ниже приводится пример контекста из средства выполнения для Linux, размещенного в GitHub.

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

Пример использования контекста runner

В этом примере рабочего процесса с помощью контекста runner задается путь к временному каталогу для записи журналов, а если рабочий процесс завершается сбоем, эти журналы отправляются в качестве артефакта.

name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - 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@v3
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

Контекст secrets

Контекст secrets содержит имена и значения секретов, доступных для экземпляра рабочего процесса. Контекст secrets недоступен для составных действий из-за соображений безопасности. Если вы хотите передать секрет в составное действие, это необходимо сделать явным образом в качестве входных данных. Дополнительные сведения о секретах см. в разделе Зашифрованные секреты.

GITHUB_TOKEN — это секрет, который автоматически создается для каждого экземпляра рабочего процесса и всегда включается в контекст secrets. Дополнительные сведения см. в разделе Автоматическая проверка подлинности токенов.

Пример содержимого контекста secrets

В следующем примере содержимого контекста secrets показан токен GITHUB_TOKEN с автоматической проверкой, а также два других секрета, доступных экземпляру рабочего процесса.

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

Пример использования контекста secrets

В этом примере рабочего процесса используется действие маркировщика, для которого требуется GITHUB_TOKEN в качестве значения входного параметра repo-token:

name: Pull request labeler
on: [ pull_request_target ]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/labeler@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Контекст strategy

Для рабочих процессов с матрицей контекст strategy содержит сведения о стратегии выполнения матрицы для текущего задания.

Пример содержимого контекста strategy

В следующем примере содержимое контекста strategy взято из последнего задания в матрице с четырьмя заданиям. Обратите внимание на разницу между числом job-index с отсчетом от нуля и свойством job-total, которое не отсчитывается от нуля.

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

Пример использования контекста strategy

В этом примере рабочего процесса с помощью свойства strategy.job-index задается уникальное имя файла журнала для каждого задания в матрице.

name: Test matrix
on: push

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

Контекст matrix

Для рабочих процессов с матрицей контекст matrix содержит свойства матрицы, определенные в файле рабочего процесса, который применяется к текущему заданию. Например, если настроить матрицу с ключами os и node, объект контекста matrix включает свойства os и node со значениями, которые используются для текущего задания.

В контексте matrix нет стандартных свойств, а есть только те, что определены в файле рабочего процесса.

Пример содержимого контекста matrix

В следующем примере содержимое контекста matrix взято из задания в матрице, у которой есть свойства os и node, определенные в рабочем процессе. Задание выполняется с сочетанием ОС ubuntu-latest и Node.js версии 16.

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

Пример использования контекста matrix

В этом примере рабочий процесс создает матрицу с ключами os и node. В нем для каждого задания с помощью свойства matrix.os задается тип средства выполнения, а с помощью свойства matrix.node — версия Node.js.

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@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

Контекст needs

Контекст needs содержит выходные данные всех заданий, которые определены как прямая зависимость от текущего задания. Обратите внимание, что сюда не входят неявно зависимые задания (например, зависимые задания зависимого задания). Дополнительные сведения об определении зависимостей заданий см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Пример содержимого контекста needs

В следующем примере содержимого контекста needs показаны сведения о двух заданиях, от которых зависит текущее задание.

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

Пример использования контекста needs

В этом примере рабочего процесса есть три задания: build, которое выполняет сборку, deploy, которому требуется задание build, а также debug, которому требуются и задание build, и deploy и которое выполняется, только если в рабочем процессе произошел сбой. Задание deploy также использует контекст needs для доступа к выходным данным задания build.

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@v3
      - 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@v3
      - run: ./deploy --build ${{ needs.build.outputs.build_id }}
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - uses: actions/checkout@v3
      - run: ./debug

Контекст inputs

Контекст inputs содержит входные свойства, передаваемые в действие или в повторно используемый рабочий процесс. Имена и типы входных данных определяются в конфигурации события workflow_call многократно используемого рабочего процесса, а входные значения передаются из jobs.<job_id>.with во внешнем рабочем процессе, который вызывает многократно используемый рабочий процесс.

Свойства в контексте inputs определяются в файле рабочего процесса. Они доступны только в повторно используемых рабочих процессах

Пример содержимого контекста inputs

Следующий пример содержимого контекста inputs взят из рабочего процесса, в котором определены входные данные build_id, deploy_target и perform_deploy.

{
  "build_id": 123456768,
  "deploy_target": "deployment_sys_1a",
  "perform_deploy": true
}

Пример использования контекста inputs в многократно используемом рабочем процессе

В этом примере многократно используемого рабочего процесса с помощью контекста inputs получаются значения входных данных build_id, deploy_target и perform_deploy, которые были переданы в многократно используемый рабочий процесс из рабочего процесса вызывающего объекта.

name: Reusable deploy workflow
on:
  workflow_call:
    inputs:
      build_id:
        required: true
        type: number
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: deploy --build ${{ inputs.build_id }} --target ${{ inputs.deploy_target }}