Automatic token authentication

GITHUB_TOKENシークレットについて

At the start of each workflow run, GitHub automatically creates a unique GITHUB_TOKEN secret to use in your workflow. このGITHUB_TOKENは、ワークフローの実行内での認証に利用できます。

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

各ジョブの開始前に、GitHub はジョブのインストールアクセストークンをフェッチします。 GITHUB_TOKENは、ジョブの完了時もしくは最大24時間後に期限切れになります。

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

ワークフロー内でのGITHUB_TOKENの利用

シークレットを参照するための標準構文 ${{ secrets.GITHUB_TOKEN }} を使用して、GITHUB_TOKEN を使用できます。 Examples of using the GITHUB_TOKEN include passing the token as an input to an action, or using it to make an authenticated GitHub Enterprise Server API request.

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

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

以下のワークフローの例ではlabeler actionを使用しています。これには、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 }}

例 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 に付与される権限を示しています。 People with admin permissions to an organization or repository can set the default permissions to be either permissive or restricted. For information on how to set the default permissions for the GITHUB_TOKEN for your enterprise, organization, or repository, see "Enforcing policies for GitHub Actions in your enterprise," "Disabling or limiting GitHub Actions for your organization," or "Managing GitHub Actions settings for a repository."

GITHUB_TOKEN の権限を変更する

個々のワークフローファイルの GITHUB_TOKEN の権限を変更できます。 GITHUB_TOKEN のデフォルトの権限が制限付きの場合は、一部のアクションとコマンドを正常に実行できるように、権限を昇格させる必要がある場合があります。 デフォルトの権限が許可の場合は、ワークフローファイルを編集して、GITHUB_TOKEN から一部の権限を削除できます。 セキュリティを強化するには、GITHUB_TOKEN に必要最小限のアクセスを許可する必要があります。

GITHUB_TOKEN が特定のジョブに対して保持していた権限は、ワークフロー実行ログの [Set up job] セクションで確認できます。 詳しい情報については、「ワークフロー実行ログを使用する」を参照してください。

ワークフローファイルの 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 つのジョブに対し 1 つのスコープに書き込み権限が付与されています。

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

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

GITHUB_TOKEN の権限は、最初は Enterprise、Organization、またはリポジトリのデフォルトに設定されています。 デフォルトがこれらのレベルのいずれかで制限付きの権限に設定されている場合、これは関連するリポジトリに適用されます。 たとえば、Organization レベルで制限付きのデフォルトを選択した場合、その Organization 内のすべてのリポジトリは、制限付きの権限をデフォルトとして使用します。 次に、ワークフローファイル内の構成に基づいて、最初にワークフローレベルで、次にジョブレベルで権限が調整されます。 最後に、ワークフローがフォークされたリポジトリからのプルリクエストによってトリガーされ、Send write tokens to workflows from pull requests 設定が選択されていない場合、権限が調整され、書き込み権限が読み取り専用に変更されます。

追加の権限を付与する

GITHUB_TOKENで利用できない権限を要求するトークンが必要な場合は、個人アクセストークンを生成して、それをリポジトリのシークレットに設定できます。

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

参考リンク

• "Resources in the REST API"