GitHub Actionsで「Resource not accessible by integration」エラーを解決する方法

GitHub Actions ワークフロー内で GitHub API を呼び出す際、「Resource not accessible by integration」エラーが発生する場合があります。これは主に、自動生成される GITHUB_TOKEN の権限設定に関連する問題です。

問題の詳細

以下のような API リクエストを実行すると:

curl -X POST -H "Accept: application/vnd.github.v3+json" \
  -H 'Authorization: token ${{ secrets.GITHUB_TOKEN }}' \
  https://api.github.com/repos/owner/repo/actions/runners/registration-token

次のエラーレスポンスが返されます:

{
  "message": "Resource not accessible by integration",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-registration-token-for-a-repository"
}

原因

このエラーは、GitHub Actions の自動トークン（GITHUB_TOKEN）に必要な権限が付与されていないために発生します。デフォルトでは、GITHUB_TOKEN には一部の読み取り権限しかなく、セルフホストランナーの登録トークン作成などの操作を実行するには不十分です。

解決方法

方法1: ワークフロー内で権限を設定する

ワークフローファイルのジョブ定義に permissions セクションを追加します:

jobs:
  print-token:
    runs-on: ubuntu-latest
    permissions:
      actions: write  # ランナー登録に必要な権限
    steps:
      # ステップの定義

TIP

必要な権限は API エンドポイントによって異なります。一般的にランナー関連の操作には actions: write 権限が必要です。

方法2: リポジトリ設定でワークフロー権限を変更する

1. GitHub リポジトリの「Settings」に移動
2. 左メニューで「Actions」→「General」を選択
3. 「Workflow permissions」セクションで「Read and write permissions」を選択

注意

この設定はリポジトリ内のすべてのワークフローに適用されます。セキュリティ上の理由から、必要な権限のみを付与することを推奨します。

方法3: パーソナルアクセストークンを使用する

より細かい権限制御が必要な場合は、パーソナルアクセストークン（PAT）を使用できます:

1. GitHub で「Settings」→「Developer settings」→「Personal access tokens」からトークンを作成
2. 必要な権限（例: repo, workflow）を選択
3. リポジトリのシークレットとしてトークンを追加
4. ワークフローでシークレットを参照

steps:
  - name: Get registration token
    run: |
      curl -X POST -H "Accept: application/vnd.github.v3+json" \
        -H "Authorization: token ${{ secrets.MY_PAT }}" \
        https://api.github.com/repos/${{ github.repository }}/actions/runners/registration-token

権限設定の詳細

さまざまな操作に必要な権限の例:

ランナー登録

permissions:
  actions: write

アーティファクト操作

permissions:
  actions: read
  contents: read

チェック実行

permissions:
  checks: write
  contents: read

証明書関連

permissions:
  id-token: write
  attestations: write

エンタープライズ環境での注意点

GitHub Enterprise Server を使用している場合、以下の点に注意してください:

• 組織またはエンタープライズレベルでのポリシー設定が権限に影響する可能性があります
• プライベートリポジトリでは追加の設定が必要な場合があります

ベストプラクティス

1. 最小権限の原則: 必要な最小限の権限のみを付与する
2. ジョブごとの権限設定: ワークフロー全体ではなく、必要なジョブにのみ権限を設定する
3. 定期的な見直し: 権限設定を定期的に見直し、不要な権限を削除する
4. 監査ログの確認: セキュリティイベントを定期的に確認する

トラブルシューティング

それでも問題が解決しない場合は、以下を確認してください:

1. トークンの有効期限
2. API エンドポイントの正確な URL
3. 組織/エンタープライズレベルの制限ポリシー
4. ネットワーク制約やファイアウォール設定

GitHub Actions の権限管理はセキュリティ上重要な要素です。必要最小限の権限を適切に設定することで、安全かつ効率的なワークフロー実行を実現できます。