GitHub Actions の GITHUB_TOKEN で push できない (permission denied)

要約

ワークフロー内で自動付与される GITHUB_TOKEN は、リポジトリ設定で 読み取り専用 に絞られているのが既定。git push や gh pr comment で Permission to ... denied が出るなら、ワークフロー側の permissions: 宣言とリポジトリの Workflow permissions を組み合わせて、必要なスコープだけを明示的に許可する。

よくある原因

1. 既定が read-only: 2023 年以降に作成されたリポジトリは Workflow permissions の既定が Read で、書き込みは明示しないと拒否される。
2. permissions: 未指定: ワークフロー / ジョブで permissions: を書いていないとリポジトリ既定が適用される。
   書き込みが必要な処理でも自動で許可されない。
3. クロスリポジトリ push: GITHUB_TOKEN は発行元リポジトリにしか書き込めない。
   別リポジトリへ push したい場合は別の認証手段が必要。
4. ブランチ保護: main の direct push 禁止やレビュー必須が設定されていると、書き込み権があっても push 自体が拒否される。

解決策

1. ワークフローで必要権限を明示

permissions:
  contents: write
  pull-requests: write
 
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git push

automatic-token-authentication に許可可能スコープの一覧がある。
最小権限の原則で必要分だけ書く。

2. リポジトリ設定を Read and write に切り替え

Settings → Actions → General → Workflow permissions を Read and write permissions に変更する。
ワークフロー側の permissions: の方が常に優先されるので、リポジトリ設定はベースラインの引き上げ用と考える。

3. 別リポジトリには PAT / App トークン

別リポジトリへ push するなら、Fine-grained PAT か GitHub App の installation token を Secrets に登録し actions/checkout の token: に渡す。

- uses: actions/checkout@v4
  with:
    repository: owner/other-repo
    token: ${{ secrets.CROSS_REPO_PAT }}

4. ブランチ保護の確認

main への直接 push を禁止していると、書き込み権があっても拒否される。
CI 経由の push が必要なら Bypass list に github-actions[bot] を追加するか、PR ベースのフローに切り替える。