Automatic token authentication

GITHUB_TOKEN シークレットについて

各ワークフロー実行の開始時に、GitHub によって、ワークフローで使用する一意の GITHUB_TOKEN シークレットが自動的に作成されます。 GITHUB_TOKEN はワークフロー実行での認証に使用できます。

GitHub Actionsを有効化すると、GitHubはリポジトリにGitHub Appをインストールします。 GITHUB_TOKEN シークレットは GitHub App インストール アクセス トークンです。 このインストールアクセストークンは、リポジトリにインストールされたGitHub Appの代わりに認証を受けるために利用できます。 このトークンの権限は、ワークフローを含むリポジトリに限定されます。 詳細については、「GITHUB_TOKEN の権限」を参照してください。

各ジョブの開始前に、GitHub はジョブのインストールアクセストークンをフェッチします。 ジョブが終了するか最大 24 時間後に、GITHUB_TOKEN の有効期限が切れます。

トークンは github.token コンテキストでも使用できます。 詳細については、「コンテキスト」を参照してください。

ワークフローでの GITHUB_TOKEN の使用

シークレットを参照するための標準構文 ${{ secrets.GITHUB_TOKEN }} を使って、GITHUB_TOKEN を使用できます。 GITHUB_TOKEN の使用例には、トークンをアクションへの入力として渡すことや、それを使用して認証済みの GitHub Enterprise Server API 要求を行うことが含まれます。

リポジトリGITHUB_TOKENを使用してタスクを実行する場合、 は新しいワークフロー実行を作成しません。 これによって、予想外の再帰的なワークフローの実行が生じないようになります。 たとえば、ワークフロー実行でリポジトリの GITHUB_TOKEN を使用してコードがプッシュされた場合、push イベントの発生時に実行するように構成されたワークフローがリポジトリに含まれている場合でも、新しいワークフローは実行されません。

例 1: 入力として GITHUB_TOKEN を渡す

次のワークフローの例では、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@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

例 2: REST API を呼び出す

GITHUB_TOKEN を使用して、認証済みの API 呼び出しを行うことができます。 以下のワークフローの例では、GitHub REST APIを使ってIssueを作成しています。

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url http(s)://HOSTNAME/api/v3/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

GITHUB_TOKEN のアクセス許可

GitHub Apps が各権限でアクセできる API エンドポイントについては、「GitHub App の権限」を参照してください。

次の表は、GITHUB_TOKEN に既定で付与されるアクセス許可を示したものです。 組織またはリポジトリへの管理者アクセス許可を持つユーザーは、既定のアクセス許可を制限なしまたは制限ありに設定できます。 エンタープライズ、組織、またはリポジトリの GITHUB_TOKEN に対して既定のアクセス許可を設定する方法については、「エンタープライズでの GitHub Actions のポリシーの適用」、「組織の GitHub Actions の無効化または制限」、または「リポジトリの GitHub Actions 設定の管理」を参照してください。

[1] プライベート リポジトリでは、フォークからの pull request がワークフローを実行できるかどうかを制御し、GITHUB_TOKEN に割り当てられたアクセス許可を構成することができます。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。

GITHUB_TOKEN のアクセス許可の変更

GITHUB_TOKEN のアクセス許可は、個々のワークフロー ファイルで変更できます。 GITHUB_TOKEN の既定のアクセス許可が制限されている場合は、一部のアクションとコマンドを正常に実行できるように、アクセス許可を昇格させる必要がある場合があります。 既定のアクセス許可が許容されている場合は、ワークフロー ファイルを編集して GITHUB_TOKEN から一部のアクセス許可を削除できます。 優れたセキュリティ プラクティスとして、GITHUB_TOKEN に必要最小限のアクセス権を付与することをお勧めします。

GITHUB_TOKEN が特定のジョブに対して保持していたアクセス許可は、ワークフロー実行ログの [ジョブを設定する] セクションで確認できます。 詳細については、「ワークフロー実行ログを使用する」を参照してください。

ワークフロー ファイル内の permissions キーを使用して、ワークフロー全体または個々のジョブの GITHUB_TOKEN のアクセス許可を変更することができます。 これにより、ワークフローまたはジョブに最低限必要な権限を設定できます。 permissions キーが使用されている場合は、すべての未指定のアクセス許可が [アクセスなし] に設定されます。ただし、metadata スコープは例外であり、常に読み取りアクセス権を取得します。

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」を参照してください。

この記事の前半の 2 つのワークフロー例は、ワークフロー レベルとジョブ レベルで使用されている permissions キーを示しています。 例 1 では、ワークフロー全体に対して 2 つのアクセス許可が指定されています。 例 2 では、単一ジョブの 1 つのスコープに書き込みアクセス許可が付与されています。

permissions キーの詳細については、「GitHub Actions のワークフロー構文」を参照してください。

ワークフロージョブの権限の計算方法

GITHUB_TOKEN のアクセス許可は最初に、エンタープライズ、組織、またはリポジトリの既定値に設定されます。 デフォルトがこれらのレベルのいずれかで制限付きの権限に設定されている場合、これは関連するリポジトリに適用されます。 たとえば、Organization レベルで制限付きのデフォルトを選択した場合、その Organization 内のすべてのリポジトリは、制限付きの権限をデフォルトとして使用します。 次に、ワークフローファイル内の構成に基づいて、最初にワークフローレベルで、次にジョブレベルで権限が調整されます。 最後に、ワークフローがフォークされたリポジトリからの pull request によってトリガーされ、 [pull request からワークフローに書き込みトークンを送信する] 設定が選択されていない場合、アクセス許可が調整され、書き込みアクセス許可はすべて読み取り専用に変更されます。

追加の権限を付与する

GITHUB_TOKEN で利用できないアクセス許可を必要とするトークンが必要な場合は、personal access tokenを作成し、それをリポジトリのシークレットとして設定できます。

1. リポジトリに対して適切な権限を持つトークンを利用もしくは生成してください。 詳しい情報については、「personal access tokenの作成」を参照してください。
2. トークンをワークフローのリポジトリにシークレットとして追加し、${{ secrets.SECRET_NAME }} 構文を使用して参照します。 詳細については、「暗号化されたシークレットの作成と使用」を参照してください。

参考資料

• "REST API のリソース"