ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
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
にアクセスできます。 セキュリティを強化するには、GITHUB_TOKEN
に付与されるアクセス許可を制限することにより、アクションに必要な最小限のアクセスのみが含まれるようにする必要があります。 詳しい情報については「GITHUB_TOKEN
の権限」を参照してください。
タスクの実行にリポジトリの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."
スコープ | デフォルトアクセス (許可) | デフォルトアクセス (制限付き) | フォークされたリポジトリ による最大アクセス |
---|---|---|---|
actions | 読み取り/書き込み | なし | 読み取り |
checks | 読み取り/書き込み | なし | 読み取り |
contents | 読み取り/書き込み | 読み取り | 読み取り |
deployments | 読み取り/書き込み | なし | read |
issues | 読み取り/書き込み | なし | 読み取り |
メタデータ | 読み取り | 読み取り | 読み取り |
パッケージ | 読み取り/書き込み | なし | 読み取り |
pages | read/write | none | read |
pull-requests | read/write | none | read |
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
で利用できない権限を要求するトークンが必要な場合は、個人アクセストークンを生成して、それをリポジトリのシークレットに設定できます。
- リポジトリに対して適切な権限を持つトークンを利用もしくは生成してください。 詳しい情報については、「個人アクセストークンを作成する」を参照してください。
- ワークフローのリポジトリにそのトークンをシークレットとして追加し、
${{ secrets.SECRET_NAME }}
構文でそれを参照してください。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。