注: 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
によって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 の設定を管理する」を参照してください。
Scope | 既定のアクセス (制限なし) | 既定のアクセス (制限あり) | パブリックにフォークされたリポジトリ からの pull request に対する最大アクセス権 |
---|---|---|---|
actions | 読み取り/書き込み | なし | 読み取り |
checks | 読み取り/書き込み | なし | 読み取り |
目次 | 読み取り/書き込み | 読み取り | 読み取り |
deployments | 読み取り/書き込み | なし | 読み取り |
ディスカッション | 読み取り/書き込み | なし | 読み取り |
issues | 読み取り/書き込み | なし | 読み取り |
metadata | 読み取り | 読み取り | 読み取り |
packages | 読み取り/書き込み | 読み取り | 読み取り |
ページ | 読み取り/書き込み | なし | 読み取り |
pull-requests | 読み取り/書き込み | なし | 読み取り |
repository-projects | 読み取り/書き込み | なし | 読み取り |
security-events | 読み取り/書き込み | なし | 読み取り |
statuses | 読み取り/書き込み | なし | 読み取り |
注:
pull_request_target
イベントによってワークフローがトリガーされると、パブリック フォークからトリガーされた場合でも、GITHUB_TOKEN
にはリポジトリの読み取り/書き込みアクセス許可が付与されます。 詳しくは、「ワークフローをトリガーするイベント」を参照してください。- プライベート リポジトリでは、フォークからの pull request がワークフローを実行できるかどうかを制御でき、
GITHUB_TOKEN
に割り当てられるアクセス許可を構成できます。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」を参照してください。 - Dependabot pull request によってトリガーされるワークフロー実行は、フォークされたリポジトリからのものであるかのように実行されるため、読み取り専用の
GITHUB_TOKEN
を使用します。 それらのワークフローの実行は、シークレットにはアクセスできません。 これらのワークフローをセキュリティで保護するための戦略については、「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 のワークフロー構文」を参照してください。
注: Organization と Enterprise のオーナーは、リポジトリ レベルで GITHUB_TOKEN
への書き込みアクセスを許可できないようにすることができます。 詳細については、「Organization について 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 でのシークレットの使用」を参照してください。