コンテキスト

コンテキストについて

コンテキストは、ワークフローの実行、ランナーの環境、ジョブ、ステップに関する情� �にアクセスする方法です。 各コンテキストは、プロパティを含むオブジェクトであり、文字列またはその他のオブジェクトにすることができます。

コンテキスト、オブジェクト、プロパティは、ワークフローの実行条件によって大きく異なります。 たとえば、matrix コンテキストはマトリックス内のジョブに対してのみ設定されます。

式構文を使用してコンテキストにアクセスできます。 詳細については、「式」を参照してく� さい。

${{ <context> }}

式の一部として、2 つの構文のいずれかを使用してコンテキスト情� �にアクセスできます。

• インデックス構文: 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 関数はどこにも使用できません。

次の表は、ワークフロー内で各コンテキストと特殊関数を使用できる� �所を示しています。 以下に一覧表示されている� �合を除き、任意の� �所で関数を使用できます。

例: ログへのコンテキスト情� �の出力

デバッグのためにコンテキストの内容をログに出力できます。 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 Webhook ペイロードの内容と同じであるため、切り捨てられています。

{
  "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@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

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

steps コンテキスト

steps コンテキストには、id が指定されていて、既に実行されている現在のジョブのステップに関する情� �が含まれています。

steps コンテキストの内容の例

この steps コンテキストの例は、id が指定された 2 つの前のステップを示しています。 最初のステップの idは checkout という名前で、2 番目は generate_number です。 generate_number ステップの出力は random_number という名前です。

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

steps コンテキストの使用例

このワークフロー例では、1 つのステップで出力として乱数を生成し、後のステップでは steps コンテキストを使用してその出力の値を読み取ります。

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

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@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

secrets コンテキスト

secrets コンテキストには、ワークフロー実行で使用できるシークレットの名前と値が含まれています。 セキュリティ上の理由から、複合アクションに secrets コンテキストは使用できません。 複合アクションにシークレットを渡すには、入力として明示的に行う必要があります。 シークレットについて詳しくは、「暗号化されたシークレット」を参照してく� さい。

GITHUB_TOKEN は、すべてのワークフロー実行に対して自動的に作成されるシークレットであり、常に secrets コンテキストに含まれます。 詳しくは、「自動トークン認証」を参照してく� さい。

secrets コンテキストの内容の例

次の secrets コンテキストの内容の例は、自動 GITHUB_TOKEN と、ワークフロー実行で使用できる他の 2 つのシークレットを示しています。

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

secrets コンテキストの使用例

次のワークフローの例では、repo-token 入力パラメーターの値として GITHUB_TOKEN を必要とするラベラー アクションを使用します。

name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

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

strategy コンテキスト

マトリックスを含むワークフローの� �合、strategy コンテキストには現在のジョブのマトリックス実行戦略に関する情� �が含まれます。

strategy コンテキストの内容の例

次の strategy コンテキストの内容の例は、4 つのジョブを含むマトリックスからのものであり、最終的なジョブから取得されたものです。 0 から始まる job-index 数値と、0 から始まらない 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@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

matrix コンテキスト

マトリックスを含むワークフローの� �合、matrix コンテキストには、現在のジョブに適用されるワークフロー ファイルで定義されているマトリックス プロパティが含まれます。 たとえば、os と node キーを使用してマトリックスを構成する� �合、matrix コンテキスト オブジェクトには、現在のジョブで使用されている値を持つ os と node プロパティが含まれます。

matrix コンテキストには標準プロパティはなく、ワークフロー ファイルで定義されているもののみとなります。

matrix コンテキストの内容の例

次の matrix コンテキストの内容の例は、ワークフローで定義された os と node マトリックス プロパティを持つマトリックス内のジョブからのものです。 そのジョブでは、ubuntu-latestOS と 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@v2
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

needs コンテキスト

needs コンテキストには、現在のジョブの直接依存関係として定義されたすべてのジョブからの出力が含まれます。 これには、暗黙的な依存ジョブ (たとえば、依存ジョブの依存ジョブ) は含まれないことに注意してく� さい。 ジョブの依存関係の定義について詳しくは、「GitHub Actions のワークフロー構文」を参照してく� さい。

needs コンテキストの内容の例

needs コンテキストの次の内容の例は、現在のジョブが依存している 2 つのジョブの情� �を示しています。

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

needs コンテキストの使用例

このワークフロー例には 3 つのジョブがあります。つまり、ビルドを実行する build ジョブ、build ジョブを必要とする deploy ジョブ、build と deploy ジョブの両方を必要とし、ワークフローにエラーがある� �合にのみ実行される debug ジョブです。 また、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@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