GitHub Actions: Fix "Resource not accessible by integration" Error

Overview

The "Resource not accessible by integration" error occurs when GitHub Actions workflows attempt to access API endpoints or resources without sufficient permissions. This commonly happens when using the default GITHUB_TOKEN to interact with GitHub's REST API, particularly for operations requiring elevated privileges like managing self-hosted runners.

Error Description

When making API requests from GitHub Actions workflows, you may encounter:

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

Root Cause

The default GITHUB_TOKEN provided to workflows has limited permissions. For repository-scoped operations, it typically only has read access to repositories and write access to packages by default. Operations requiring administrative or write permissions to actions/runner management will fail with this error.

Solutions

Method 1: Job-Level Permissions (Recommended)

Add a permissions section to your job definition to grant the necessary access:

jobs:
  print-token:
    runs-on: ubuntu-latest
    permissions:
      actions: write  # Required for runner management
    steps:
      - name: Get registration token
        run: |
          curl -X POST \
          -H "Accept: application/vnd.github.v3+json" \
          -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
          https://api.github.com/repos/${{ github.repository }}/actions/runners/registration-token

Available permission scopes include:

• actions: read/write - For Actions and runner management
• contents: read/write - For repository contents
• packages: read/write - For package registry
• checks: write - For check suites and runs
• id-token: write - For OIDC tokens
• attestations: write - For provenance attestations

WARNING

For private repositories on non-Enterprise plans, some permissions like attestations: write may not be available.

Method 2: Repository Settings Configuration

Adjust the default permissions at the repository level:

1. Go to your repository's Settings
2. Navigate to Actions → General
3. Scroll to Workflow permissions
4. Select Read and write permissions
5. Click Save

TIP

This approach affects all workflows in the repository. For finer control, use job-level permissions instead.

Method 3: Personal Access Token (PAT)

Create a Personal Access Token with the required scopes and use it instead of GITHUB_TOKEN:

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

Security Note

PAT tokens have broader access than GITHUB_TOKEN. Always limit PAT scopes to minimum required permissions and store them as repository secrets.

Common Permission Requirements

Different API operations require specific permissions:

Operation	Required Permissions
Runner registration token	actions: write
Download artifacts	actions: read
Upload artifacts	actions: write
Code checkout	contents: read
Test reporting	checks: write

Example: Complete Workflow with Proper Permissions

name: Get Runner Token

on:
  push:
    branches: [main]

jobs:
  obtain-token:
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: read
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Get runner registration token
        id: get-token
        run: |
          response=$(curl -s -X POST \
            -H "Accept: application/vnd.github.v3+json" \
            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
            https://api.github.com/repos/${{ github.repository }}/actions/runners/registration-token)
          echo "token=$(echo $response | jq -r '.token')" >> $GITHUB_OUTPUT

Troubleshooting Tips

1. Verify current token permissions:

   curl -H "Authorization: token $TOKEN" https://api.github.com/repos/owner/repo

2. Check API response for specific permission requirements:

   curl -I -X POST -H "Authorization: token $TOKEN" https://api.github.com/repos/owner/repo/actions/runners/registration-token

3. Review GitHub Actions logs for detailed error messages about missing permissions.

Best Practices

• Always use the least privilege principle when granting permissions
• Prefer job-level permissions over repository-wide settings
• Regularly review and update token permissions
• Use environment-specific secrets for different deployment stages
• Monitor GitHub's permission model changes through official documentation

By properly configuring permissions using these methods, you can resolve the "Resource not accessible by integration" error and ensure your GitHub Actions workflows have the necessary access to perform their intended operations.