GitHub Actions で「Resource not accessible by integration」エラーの解決法

2025.10.28

GitHub Actions で Pull Request（PR）をトリガーにワークフローを動かした際、次のようなエラーが出ることがあります。

Resource not accessible by integration

このエラーは、単純な設定ミスではなく、GitHub Actions の権限モデルを理解していないと再発しやすい問題です。
この記事では、原因の仕組みから安全な解決方法までを体系的に解説します。

目次

よくある原因：PR由来のワークフローに権限がない

このエラーの多くは、PRがリポジトリのリソース（Issue、Label、Comment など）を操作しようとした際に発生します。
特に外部コントリビューターが fork から送った PR では発生頻度が高くなります。

理由は、GitHub がセキュリティ保護のために、fork から実行されるワークフローに対して GITHUB_TOKEN の書き込み権限を付与しない 仕組みになっているからです。
結果として、ラベル追加やコメント投稿のような操作が「許可されないリソースへのアクセス」として拒否されます。

原因の構造を理解する

GitHub Actions の権限は、イベントの種類と発火元によって変化します。次の2点を理解しておくと仕組みが整理できます。

  1. GITHUB_TOKEN の権限はイベント発火元で変わる
    • 自リポジトリ内のイベント：書き込み可能
    • 外部 fork からのイベント：読み取りのみ
  2. イベントタイプによってコンテキストが異なる
    • pull_request：fork 側のコンテキストで実行される
    • pull_request_target：ベースリポジトリのコンテキストで実行される

この違いを理解していないと、同じ設定ファイルでも状況によって結果が変わるように見えてしまいます。

再現例：ラベル付与アクションでの失敗

次の設定を例に考えてみます。

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  add-label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions-ecosystem/action-add-labels@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          labels: "needs-review"

このワークフローは PR が作成されたときに自動でラベルを追加するものですが、fork から送られた PR の場合は次のように失敗します。

Resource not accessible by integration

原因は、GITHUB_TOKEN が pull-requests: write 権限を持たない状態で実行されているためです。

安全な解決策三つ

1. permissions を明示的に指定する

デフォルトでは GITHUB_TOKEN の権限が制限されているため、必要な権限を明示的に設定します。

permissions:
  pull-requests: write
  contents: write

これで、同一リポジトリ内の PR に対しては問題なく動作します。
ただし、外部 fork からの PR は依然として制限される点に注意してください。

2. pull_request_target イベントを使用する

pull_request_target はベースリポジトリのコンテキストで実行されるため、エラーを回避できます。

on:
  pull_request_target:
    types: [opened, labeled]

ただし、PR で変更されたコードを直接実行してしまうとセキュリティリスクがあります。
安全に運用するためには、チェックアウト時にベースブランチを指定します。

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.pull_request.base.ref }}

この設定で、外部の変更を直接実行せずに安全な権限で処理できます。

3. Personal Access Token（PAT）を利用する

どうしても外部 PR からリソース操作を行う必要がある場合、専用の Bot アカウントを作成し、最小限の権限で PAT を発行します。

with:
  github_token: ${{ secrets.BOT_TOKEN }}

この方法は柔軟ですが、管理コストとセキュリティリスクを伴うため、最後の手段として扱うべきです。

設計チェックリスト

チェック項目状況
permissions を明示的に設定している確認
pull_request_target の挙動を理解している確認
fork からの PR で制限が発生する点を把握している確認
トークンのスコープを最小限にしている確認

まとめ：理解して設計すれば再発しない

「Resource not accessible by integration」エラーは、GitHub Actions のセキュリティモデルを理解すれば確実に防げる問題です。

単にエラーを回避する設定を探すのではなく、
どのイベントで、誰の権限で、どのリソースにアクセスしているのかを意識することで、安全で再現性の高いワークフローを構築できます。

ポイント

  • エラーの原因は fork からの PR による権限制限
  • 解決策は「permissions指定」「pull_request_target」「PAT利用」の三つ
  • 安易な設定変更よりも権限モデルの理解が重要

GitHub Actions は正しく理解して設計すれば、より信頼性と安全性の高い自動化を実現できます。

タイトルとURLをコピーしました