自動トークン認証

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

GITHUB_TOKEN を使う GitHub Actions ワークフローによってプッシュされたコミットでは、GitHub Pages ビルドがトリガーされません。

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

このワークフローの例では、GH_TOKEN 入力パラメーターの値として GITHUB_TOKEN を必要とする GitHub CLI が使用されます。

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_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 のポリシーを適用する」、「Organization について 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 キーを示します。

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

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

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

追加の権限を付与する

GITHUB_TOKEN で利用できないアクセス許可を要求するトークンが必要な場合、GitHub App を作成し、ワークフロー内でインストール アクセス トークンを生成できます。 詳しくは、「GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する」を参照してください。 または、personal access tokenを作成して、シークレットとしてリポジトリに格納し、ワークフロー内のトークンを ${{ secrets.SECRET_NAME }} 構文で使用することができます。 詳細については、「個人用アクセス トークンを管理する」および「GitHub Actions でのシークレットの使用」を参照してください。

参考資料

• 「REST API のレート制限」