AIものさし

GitHub ActionsのResource not accessible by integrationを権限別に切り分ける

GitHub ActionsのResource not accessible by integrationを、token・API endpoint・event・repository policyから切り分けます。

AIものさし編集部

GitHub Actionsは成功しているのに、Pull Request作成やレビュー投稿、Release更新などで「Resource not accessible by integration」と表示されたら、最初にYAMLの権限を一律で広げないでください。このエラーだけでは、どのtoken・resource・permissionが不足したかまでは分かりません。失敗したAPI endpoint、認証に使ったtokenの種類、workflowが動いたevent、repositoryやorganizationのポリシーを照合します。

特に、fork由来のpull requestやDependabotのworkflowは、通常のpush実行と同じ書き込み権限にならないことがあります。GitHub Actionsが自動発行するGITHUB_TOKENならworkflow/jobのpermissions設定を確認します。GitHub App tokenやPersonal Access Tokenなら、発行元アプリの権限とインストール先、tokenの対象repositoryを別に確認してください。まず失敗した一つの処理に必要な最小権限だけを特定し、信頼できるテスト環境で再現します。

目次

先に集める4つの証拠

権限修正を始める前に、失敗したjobのログから次を控えます。トークン値やAuthorization headerはコピー・共有しません。ログにsecretが出ていないかも確認し、見つかった場合は共有せず、組織のsecret対応手順に従います。

表は横にスクロールできます

確認項目どこを見るかなぜ必要か
失敗した操作とendpointAPI呼び出し、Action名、HTTP methodとpath必要なpermissionが操作ごとに異なるため
tokenの種類workflow内の認証方法、Actionの入力GITHUB_TOKEN、App token、PATでは管理場所が違うため
eventの種類Actions runのevent、head/base repositoryfork PRやDependabotでは権限が制限されるため
対象resourcerepository、PR、branch、release、package等tokenが有効でも対象resourceに届かない場合があるため

エラーにHTTP 403が含まれていても、権限不足だと即断しません。APIのresponse body、GitHub側の監査・実行ログ、repository settingsで拒否理由が出ていないかを確認します。認証情報そのものやtoken全文は監査メモに残さず、token種別・権限名・発行元だけを記録してください。

1. 失敗したendpointから必要な権限を調べる

GitHub REST APIでは、同じrepository内の操作でもendpointごとに必要なfine-grained permissionが異なります。たとえば、Pull Requestを作る処理とReleaseを作る処理を、同じ「GitHubを書き込む権限」として扱えません。エラーが出たAction名だけでなく、そのActionが呼び出すendpointとmethodを特定し、該当する公式API referenceの「Fine-grained access tokens」やpermission欄を確認します。

ログが「Resource not accessible by integration」だけでendpointを示さない場合は、処理を小さく分けます。どのstepで失敗したか、直前に何を呼んだか、Actionが内部で使うAPIが分かるかを確認します。複数操作をまとめたActionなら、verbose loggingを有効にする前にsecretをマスクできるか確認してください。安全に詳細ログを出せない場合は、Actionの公式ドキュメントやソースで呼び出し先を調べ、ログへtokenを追加しないでください。

表は横にスクロールできます

操作例先に調べる対象すぐにしないこと
Pull Request作成pull request作成APIと対象branch/repositorycontentsや全permissionを一括writeにする
IssueやPR comment対象APIのissue/pull request permission別resource向けの権限まで広げる
Release作成・更新Release endpointとcontents等の必要権限PATへ置き換えて原因を隠す
packageへのpushpackage registryと対象packageのアクセス設定repository tokenがすべてのpackageへ届くと仮定する

表は調査の入口です。必要権限名を固定で断定する一覧ではありません。利用するAPIの現行referenceと認証方式で確定してください。

応答ヘッダーから要求permissionの候補を読む

GitHub Appまたはfine-grained PATでREST APIの権限不足を調べる場合、公式資料は応答の X-Accepted-GitHub-Permissions ヘッダーも案内しています。既に取得している失敗応答からこの項目を確認し、失敗したmethod・endpointの公式referenceと照合します。リクエストのAuthorizationやtoken値を診断メモへ貼らないでください。GitHub：Troubleshooting the REST API（新しいタブで開く）

このヘッダーは、tokenが今持つ権限の一覧ではなく、endpoint側が要求する権限を調べる手掛かりです。

表は横にスクロールできます

区切り公式資料の読み方避ける解釈
カンマ同じpermission setで必要な権限の組どれか一つだけ付ければよい
セミコロン複数の代替permission setすべてのsetを足して最大権限にする

例えば contents=read ならContentsのreadが要求候補です。複数setが返る場合は、用途と認証方式に合う最小の組をendpointの説明で確認します。ヘッダーが記録されていない場合も、必要権限を推測で補わず、referenceとtoken発行元・対象repositoryの確認へ戻ります。

権限名が分かっても、Appのinstallation対象、resource owner、fork由来の実行条件などの確認は残ります。また、この説明をclassic PATのscope一覧や、Actionsの実効権限をそのまま表示する方法として扱いません。例は応答の読み方であり、実repositoryへAPIを実行して確かめた結果ではありません。

2. GITHUB_TOKENならworkflowとjobの設定を見る

GITHUB_TOKENは、workflow jobの開始時にGitHub Actionsが発行する、そのrepository向けのGitHub App installation tokenです。tokenの権限はworkflowまたはjobのpermissionsで調整できます。workflow全体に設定した値とjob単位の設定を両方確認し、実際に失敗したjobへどのpermissionが適用されているかを追います。

YAMLにpermissionsが一つもない場合でも、実効権限はrepositoryやorganization側の既定設定、eventの種類などに左右されます。次のように確認します。

  1. workflowファイルの最上位にpermissionsがあるか読む。

  2. 失敗したjobに個別permissionsがあるか確認する。job設定がある場合はそのjobの実効値を確認する。

  3. Actions settingsのWorkflow permissionsとorganization policyを確認する。

  4. API endpointの公式referenceで必要なpermissionを確認する。

  5. 必要な対象だけreadまたはwriteを付け、その他は最小権限にする。

例として、PR作成が失敗した場合でも、単純に全権限writeへ変えず、呼び出し先APIが要求するpull request系のpermissionとevent制約を先に確かめます。contentsを書き換えるstepが同じjobにあるなら、PR作成に不要なその権限を分けてjob単位で与える方法も検討できます。これは設定例の考え方であり、実際のworkflowへそのまま貼るテンプレートではありません。

GitHub ActionsのGITHUB_TOKENはworkflow実行中のjobに結び付いており、無関係なrepositoryへ自由にアクセスするtokenではありません。別repositoryのprivate Actionやreusable workflowを呼ぶケースでは、呼び出し元tokenのYAML設定だけでなく、利用先repositoryのActions access設定も確認します。

3. fork PR・Dependabotでは通常のpushと分ける

forkからのpull requestは、変更を送った人がbase repositoryの信頼済み共同作業者とは限りません。そのためGitHubは安全のため、fork PRで動くworkflowのGITHUB_TOKENをread-onlyへ制限し、通常はrepository secretsも渡しません。Dependabotのpush、pull_request、pull_request_review、pull_request_review_commentイベントで起動するworkflowは、既定ではfork由来と同様にread-onlyのGITHUB_TOKENとなり、GitHub Actions secretsは提供されません。一方、Dependabot secretsは利用できるため、secrets全般が使えないという意味ではありません。repository管理者が書き込みtoken送信を明示許可する例外設定はありますが、これはセキュリティ境界を広げる判断です。

この制約のとき、YAMLへwrite permissionを足しても、eventの安全制限が適用されて期待どおりの書き込みにならない場合があります。次を確認します。

  • runのeventがpull_request、push、workflow_dispatch等のどれか。

  • PRのhead repositoryがbase repositoryと同じかforkか。

  • Dependabotが作成したPRか。

  • repository / organizationのActions設定でfork workflowの承認やwrite tokenがどう制御されているか。

  • secretが利用できないeventで、workflowがsecret必須のstepへ進んでいないか。

fork PRでPRコメントやレビューを自動投稿したい場合、誰の権限で何を実行するのか、攻撃者が変更したコードを実行しない設計になっているかを先に検討します。pull_request_targetはbase repository側の高い権限とsecretへアクセスする可能性があるeventです。権限エラーを避ける目的だけで切り替えたり、forkの未信頼コードをcheckoutして実行したりしないでください。write tokenやsecretを渡す設定も、管理者のセキュリティ判断なしに変更しません。

4. GitHub App tokenやPATは別の権限表で確認する

workflowがGITHUB_TOKENではなくGitHub App installation tokenを使う場合、Appに定義された権限、Appがインストールされているrepository、発行時に指定した対象を確認します。Appに必要なpermissionがない場合、workflow YAMLのGITHUB_TOKEN permissionsを変えても解決しません。まずtokenを発行したApp名とinstallation先を確認し、どのendpointに必要なpermissionが不足したかをApp設定の管理者に伝えます。

PATを利用している場合も同じで、classic tokenかfine-grained tokenか、許可repository、repository/organization policy、token ownerの権限・有効状態を区別します。より広いPATへ置き換えるのは、原因を隠し、長期間有効な認証情報を増やす結果になり得ます。tokenの差し替えは最初の診断手段にせず、tokenの種類とアクセス範囲を確認してから管理者の手順で行います。

5. API permission以外のブロックも分ける

権限のように見えるエラーでも、GitHub Actions自体がrepositoryで許可されていない、特定のActionやreusable workflowが制限されている、organization policyがworkflowの実行や書き込みを止めていることがあります。repositoryのSettings → Actions → GeneralでActionsの許可範囲、fork PR実行・承認設定、workflow permissions、private repositoryのActions accessを確認します。organization配下なら、repository設定で変更できずorganization ownerだけが管理できる項目があります。

また、tokenが対象repositoryに対して有効でも、権限を持つユーザーやAppがそのbranch/resourceを操作できるとは限りません。protected branch rules、Rulesets、required review、environment protection、package accessなど、対象resource側の制約を確認します。変更権限がなければ、失敗ログ・API endpoint・run event・token種別・対象resourceをまとめ、管理者に「何のpermissionを付けるか」ではなく「どの拒否理由を確認してほしいか」を伝えます。

原因別の判定表

表は横にスクロールできます

観察した状況可能性の高い確認先修正の方向
同じeventでreadは成功、特定write APIだけ失敗endpointのpermission、workflow/job permissionAPI referenceに合わせ、失敗jobに最小のwrite権限
pushでは成功し、fork PRでだけ失敗fork由来のread-only制約、secret未提供eventを前提にworkflowを安全に分ける。policy変更は管理者判断
GITHUB_TOKENでは失敗し、App tokenを使う設計App permission、installation scope、対象repositoryApp管理者が必要最小permissionとinstallationを確認
private reusable workflow / Actionの取得で失敗呼び出し元・利用先のActions access利用先repositoryの共有設定とorganization policy
PR作成後のbranch更新だけ失敗protected branch、Rulesets、required reviewtokenを広げる前にbranch側の保護ルールを確認
workflowが起動しない、または承認待ちActions enabled、fork approval policy、organization settings実行制御を管理者へ確認。API権限エラーと混同しない

同じエラー表示でも、認証・event・API・resource policyのどこで拒否されたかで修正先が変わります。複数候補がある場合は、一度に設定をいくつも変えず、確認できた原因から一つずつ扱います。

安全な再テスト手順

  1. 失敗runのevent、endpoint、resource、token種別を記録する。secret値は記録しない。

  2. GitHubの公式API referenceでendpointの必要permissionを確認する。

  3. GITHUB_TOKEN、App token、PATのどれが実際に使われたか確認する。

  4. fork / Dependabotの制約、workflow/job permissions、repository / organization policyを確認する。

  5. 必要な変更を承認されたテストbranchまたは安全なrepositoryで一つだけ行う。

  6. 同じeventと処理対象で再実行し、失敗したAPIだけでなく後続処理も確認する。

  7. 不要になった検証権限を戻し、変更内容と結果を記録する。

Workflowのpermissionを広げると、同じjob内の全stepがそのtokenを使える場合があります。権限が必要なstepを別jobへ分ける、read-only jobとwrite jobを分ける、実行対象branchを限定するなど、権限を使う範囲自体を小さくできないか考えてください。未信頼のpull requestコードとwrite tokenやsecretsを同じjobで扱わないことが基本です。

そのまま管理者へ渡せる調査メモ

以下を埋めて共有すると、権限を広げる前に再現条件と確認箇所を揃えられます。

  • Article／Workflow run URL：

  • Repositoryと対象resource：

  • 発生した日時・timezone：

  • Event種別とPRのhead/base：

  • 失敗したjob / step：

  • API method・endpoint：

  • HTTP ステータスとエラー本文（secretを除去）：

  • 使用したtoken種別（token値は書かない）：

  • workflow/jobのpermissions設定：

  • App installationやPATの対象repository：

  • repository／organization／branch policyの確認結果：

  • 期待した処理と実際の結果：

管理者から権限追加を提案された場合は、追加対象のpermission名、対象repository、必要なevent、付与先token、不要になったときの戻し方を確認してから変更します。tokenの値をIssueや通常のログへ貼らず、認証情報の扱いは組織のSecret運用に従ってください。

読後の判断

このエラーを見たら、最初に「GITHUB_TOKENの権限が足りない」と決めず、endpoint・token種別・event・対象resourceの4点を揃えます。GITHUB_TOKENならworkflowとjobの権限、fork PRやDependabotなら読み取り制限、App tokenならApp権限とinstallation範囲、repository側ならActionsやbranch policyを確認します。

必要な権限が公式referenceから分かる場合だけ、そのpermissionを必要なjobまたはAppへ最小限付与し、安全な条件で再テストしてください。forkの未信頼コードにwrite tokenやsecretを渡す必要がある構成なら、workflowを変更せず管理者・Security担当へ相談するのが次の行動です。

Sources