GITHUB_TOKEN のアクセス許可の制御

概要

permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳しくは、「自動トークン認証」を参照してください。

permissions は、最上位のキーとして、ワークフロー内のすべてのジョブに適用するか、または特定のジョブ内で使用できます。 特定のジョブ内に permissions キーを追加すると、GITHUB_TOKEN を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳細については、「jobs.<job_id>.permissions」を参照してください。

以下の表に示すように、使用可能なアクセス許可ごとに、read (該当する場合)、write、または none のいずれかのアクセス レベルを割り当てることができます。 write には read が含まれます。 これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

使用可能なアクセス許可と、それぞれがアクションに実行を許可する内容の詳細:

権限	GITHUB_TOKEN を使ってアクションに許可する内容
actions	GitHub Actions を操作します。 たとえば、actions: write は、アクションによるワークフロー実行の取り消しを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。
attestations	構成証明の認証作業 たとえば、 attestations: write ビルドの成果物構成証明を生成するアクションが許可されます。 詳細については、「アーティファクトの構成証明を使用して構築の実績を確立する」を参照してください
checks	チェック実行とチェック スイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。
contents	リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。
deployments	デプロイを操作します。 たとえば、deployments: write は、アクションによる新しいデプロイの作成アクションを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。
discussions	GitHub ディスカッションで作業します。 たとえば、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
  attestations: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: 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