概要
permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳しくは、「自動トークン認証」を参照してください。
permissions は、最上位のキーとして、ワークフロー内のすべてのジョブに適用するか、または特定のジョブ内で使用できます。 特定のジョブ内に permissions キーを追加すると、GITHUB_TOKEN を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳細については、「jobs.<job_id>.permissions」を参照してください。
次の表に示すように、使用可能なスコープごとに、read、write、または none のいずれかのアクセス許可を割り当てることができます。 これらのスコープのいずれかにアクセス権を指定すると、指定されていないすべてのスコープが none に設定されます。
使用可能なスコープと、それぞれがアクションに実行を許可する内容の詳細:
| Scope | GITHUB_TOKEN を使ってアクションに許可する内容 |
|---|---|
actions | GitHub Actions を操作します。 たとえば、actions: write は、アクションによるワークフロー実行の取り消しを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
checks | チェック実行とチェック スイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents:write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
deployments | デプロイを操作します。 たとえば、deployments: write は、アクションによる新しいデプロイの作成アクションを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
discussions | GitHub Discussions を操作します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」を参照してください。 |
id-token | OpenID Connect (OIDC) トークンをフェッチします。 これには id-token: write が必要です。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください |
issues | イシューを操作します。 たとえば、issues: write は、アクションがイシューにコメントを追加することを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
packages | GitHub Packages を操作します。 たとえば、packages: write は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。 詳しくは、「GitHub Packagesの権限について」を参照してください。 |
pages | GitHub Pages を操作します。 たとえば、pages: write は、アクションによる GitHub Pages のビルドの要求を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
pull-requests | pull request を操作します。 たとえば、pull-requests: write は、アクションによる pull request へのラベルの追加を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
repository-projects | GitHub プロジェクト (クラシック) を操作します。 たとえば、repository-projects: write は、アクションによるプロジェクト (クラシック) への列の追加を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
security-events | GitHub コード スキャンと Dependabot アラートを操作します。 たとえば、security-events: read はアクションによるリポジトリの Dependabot アラートの一覧表示を許可し、security-events: write はアクションによるコード スキャン アラートの状態の更新を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」の「'コード スキャン アラート' のリポジトリのアクセス許可」と「'Dependabot アラート' のリポジトリのアクセス許可」を参照してください。 |
statuses | コミットの状態を操作します。 たとえば、statuses:read は、アクションが特定の参照のコミット状態を一覧表示することを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
GITHUB_TOKEN スコープのアクセスの定義
permissions キー内で使用可能なスコープの値として read、write、または none を指定することで、GITHUB_TOKEN が許可するアクセスを定義できます。
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
id-token: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
これらのスコープのいずれかにアクセス権を指定すると、指定されていないすべてのスコープが none に設定されます。
利用可能なすべてのスコープに対して read-all または write-all どちらかのアクセス権を定義するには、以下の構文が使えます。
permissions: read-all
permissions: write-all
次の構文を使用して、使用可能なすべてのスコープのアクセス許可を無効にすることができます。
permissions: {}
フォークされたリポジトリのアクセス許可を変更する
permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」を参照してください。
ワークフロー内のすべてのジョブの GITHUB_TOKEN アクセス許可の設定
設定がワークフロー内のすべてのジョブに適用されるように、ワークフローの最上位レベルで permissions を指定できます。
例: ワークフロー全体の GITHUB_TOKEN アクセス許可の設定
この例では、ワークフロー内のすべてのジョブに適用される GITHUB_TOKEN に設定されているアクセス許可を示しています。 すべての権限に読み取りアクセスが付与されます。
name: "My workflow"
on: [ push ]
permissions: read-all
jobs:
...
特定のジョブの GITHUB_TOKEN アクセス許可を設定する
特定のジョブについて、jobs.<job_id>.permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳しくは、「自動トークン認証」を参照してください。
ジョブ定義内で権限を指定することで、必要に応じて、ジョブごとに GITHUB_TOKEN に異なる権限のセットを構成できます。 または、ワークフロー内のすべてのジョブの権限を指定することもできます。 ワークフロー レベルでのアクセス許可の定義については、permissions を参照してください。
例: ワークフロー内の 1 つのジョブの GITHUB_TOKEN アクセス許可を設定する
この例は、stale という名前のジョブにのみ適用される GITHUB_TOKEN に設定されているアクセス許可を示しています。 書き込みアクセス権は、issues スコープと pull-requests スコープに対して付与されます。 他のすべてのスコープにはアクセスできません。
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v5