自動トークン認証

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