注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
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
コンテキストを介して GITHUB_TOKEN
にアクセスできます。 セキュリティを強化するには、GITHUB_TOKEN
に付与されるアクセス許可を制限することにより、アクションに必要な最小限のアクセスのみが含まれるようにする必要があります。 詳細については、「GITHUB_TOKEN
の権限」を参照してく� さい。
リポジトリ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 設定の管理」を参照してく� さい。
Scope | 既定のアクセス (制限なし) | 既定のアクセス (制限あり) | 最大アクセス (フォークされたリポジトリによる) |
---|---|---|---|
actions | 読み取り/書き込み | なし | 読み取り |
checks | 読み取り/書き込み | なし | 読み取り |
目次 | 読み取り/書き込み | 読み取り | 読み取り |
deployments | 読み取り/書き込み | なし | 読み取り |
issues | 読み取り/書き込み | なし | 読み取り |
metadata | 読み取り | 読み取り | 読み取り |
packages | 読み取り/書き込み | なし | 読み取り |
ページ | 読み取り/書き込み | なし | 読み取り |
pull-requests | 読み取り/書き込み | なし | 読み取り |
repository-projects | 読み取り/書き込み | なし | 読み取り |
security-events | 読み取り/書き込み | なし | 読み取り |
statuses | 読み取り/書き込み | なし | 読み取り |
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を作成し、それをリポジトリのシークレットとして設定できます。
- リポジトリに対して適切な権限を持つトークンを利用もしくは生成してく� さい。 詳しい情� �については、「personal access tokenの作成」を参照してく� さい。
- トークンをワークフローのリポジトリにシークレットとして追� し、
${{ secrets.SECRET_NAME }}
構文を使用して参照します。 詳細については、「暗号化されたシークレットの作成と使用」を参照してく� さい。