Automatic token authentication

GitHubは、GitHub Actionsの代理で認証を受けるために利用できるトークンを提供します。

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コンテキストにもあります。 詳細については、「コンテキスト」を参照してください。

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

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

重要: ワークフローが GITHUB_TOKEN をアクションに明示的に渡さない場合でも、アクションは github.token コンテキストを介して GITHUB_TOKEN にアクセスできます。 セキュリティを強化するには、GITHUB_TOKEN に付与されるアクセス許可を制限することにより、アクションに必要な最小限のアクセスのみが含まれるようにする必要があります。 詳しい情報については「GITHUB_TOKENの権限」を参照してください。

リポジトリのGITHUB_TOKENを使ってGitHub Actions アプリケーションの代わりにタスクを実行した場合、その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@v2
        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_commit:
    runs-on: ubuntu-latest 
    permissions:
      issues: write 
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api.github.com/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 enterprise, 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 GitHub Actions policies in your enterprise account," "Disabling or limiting GitHub Actions for your organization," or "Managing GitHub Actions settings for a repository."

スコープデフォルトアクセス
(許可)
デフォルトアクセス
(制限付き)
フォークされたリポジトリ
による最大アクセス
actions読み取り/書き込みなし読み取り
checks読み取り/書き込みなし読み取り
contents読み取り/書き込み読み取り読み取り
deployments読み取り/書き込みなし読み取り
issues読み取り/書き込みなし読み取り
メタデータ読み取り読み取り読み取り
パッケージ読み取り/書き込みなし読み取り
pull requests読み取り/書き込みなし読み取り
repository projects読み取り/書き込みなし読み取り
security events読み取り/書き込みなし読み取り
statuses読み取り/書き込みなし読み取り

ノート: DependabotのPull Requestによってトリガーされたワークフローの実行は、フォークされたリポジトリからのように実行されるので、読み取りのみのGITHUB_TOKENを使用します。 それらのワークフローの実行は、シークレットにはアクセスできません。 これらのワークフローをセキュアに保つための方針については、「GitHub Actionsとワークフローをセキュアに保つ: pwnリクエストの回避」を参照してください。

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からワークフローに書き込みトークンを送る)を選択している場合があります。 For more information, see "Managing GitHub Actions settings for a repository."

この記事の前半の 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 }}構文でそれを参照してください。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。

このドキュメントは役立ちましたか?

プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?