Fix github-actions 'Resource not accessible by integration' Error: Complete Guide

Stephen Jones
Github
March 13, 2023

Table of Contents

If you’re working with github-actions and encountering the “Resource not accessible by integration” error, you’re dealing with one of the most common github-actions permission issues. This error typically appears when your workflow lacks the necessary permissions to perform operations like creating pull requests, updating issues, or accessing repository resources.

This comprehensive guide will show you exactly how to fix this github-actions error, understand GITHUB_TOKEN permissions, and prevent it from happening again.

Understanding the “Resource not accessible by integration” Error

The complete error message typically looks like this:

RequestError [HttpError]: Resource not accessible by integration
    at /__w/_actions/actions/github-script/v3.1.0/dist/index.js:2137:23
    at processTicksAndRejections (internal/process/task_queues.js:97:5) {
Error: Unhandled error: HttpError: Resource not accessible by integration
  status: 403

This github-actions permission error occurs when your workflow attempts to perform an operation that requires permissions it doesn’t currently have. This is github’s security mechanism working as intended—workflows have restricted permissions by default to protect your repositories.

How to Fix “Resource not accessible by integration” Error

Quick Fix: Configure GITHUB_TOKEN Permissions

The most effective solution is to explicitly define permissions in your github-actions workflow file. Here are the most common permission configurations:

For OIDC token workflows:

permissions:
  id-token: write   # Required for requesting jwt tokens
  contents: read    # Required for actions/checkout

For workflows that update pull requests and issues:

permissions:
  id-token: write        # Required for OIDC/jwt tokens
  contents: read         # Required for repository access
  issues: write          # Required for creating/updating issues
  pull-requests: write   # Required for creating/updating PRs

For comprehensive workflow permissions:

permissions:
  id-token: write        # OIDC token access
  contents: write        # Repository content access
  issues: write          # Issue management
  pull-requests: write   # PR management
  checks: write          # Check runs
  statuses: write        # Commit statuses

Understanding github-actions Permissions

When you specify any permissions in your workflow, github-actions switches from the default permissive mode to an explicit permission model. This means you must declare all permissions your workflow needs.

Default permissions (when none specified):

Most repository operations are allowed
Suitable for simple workflows

Explicit permissions (when any permission is specified):

Only declared permissions are granted
More secure but requires careful configuration
Required when using OIDC or advanced features

Real-World Example: Terraform PR Comments with OIDC

Here’s a practical example that demonstrates the permission issue and solution. This workflow updates pull requests with Terraform plan results while using OIDC authentication:

The Original Working Workflow

name: Terraform PR Comment
on:
  pull_request:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Terraform Plan
        id: terraform_plan
        run: terraform plan
        
      - name: Update Pull Request
        uses: actions/github-script@v7
        if: github.event_name == 'pull_request'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const output = `${ "${{ steps.terraform_fmt.outcome }}" == "success" ? "✅" : "❌" } Terraform Format and Style 🖌
            ${ "${{ steps.terraform_init.outcome }}" == "success" ? "✅" : "❌" } Terraform Initialization ⚙️
            ${ "${{ steps.terraform_plan.outcome }}" == "success" ? "✅" : "❌" } Terraform Plan 📖
            ${ "${{ steps.terraform_validate.outcome }}" == "success" ? "✅" : "❌" } Terraform Validation 🤖

            *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            })

The Problem: Adding OIDC Breaks Permissions

When OIDC integration was added to work with github Enterprise, the workflow needed these permissions:

permissions:
  id-token: write
  contents: read

However, adding explicit permissions removes all default permissions, causing the “Resource not accessible by integration” error when trying to comment on pull requests.

The Solution: Complete Permission Configuration

name: Terraform PR Comment with OIDC
on:
  pull_request:
    branches: [main]

# Explicit permissions required when using OIDC
permissions:
  id-token: write        # Required for OIDC jwt tokens
  contents: read         # Required for actions/checkout
  issues: write          # Required for commenting on PRs (PRs are issues)
  pull-requests: write   # Required for PR-specific operations

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Configure AWS credentials with OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1
        
      - name: Terraform Plan
        id: terraform_plan
        run: terraform plan
        
      - name: Update Pull Request
        uses: actions/github-script@v7
        if: github.event_name == 'pull_request'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const output = `## Terraform Plan Results
            
            ${ "${{ steps.terraform_fmt.outcome }}" == "success" ? "✅" : "❌" } **Terraform Format and Style** 🖌
            ${ "${{ steps.terraform_init.outcome }}" == "success" ? "✅" : "❌" } **Terraform Initialization** ⚙️
            ${ "${{ steps.terraform_plan.outcome }}" == "success" ? "✅" : "❌" } **Terraform Plan** 📖
            ${ "${{ steps.terraform_validate.outcome }}" == "success" ? "✅" : "❌" } **Terraform Validation** 🤖

            *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            })

Common github-actions Permission Scenarios

Here are the most frequently needed permission combinations for different workflow types:

Basic Repository Operations

permissions:
  contents: write        # Push commits, create releases
  pull-requests: write   # Create/update PRs
  issues: write         # Create/update issues

Package Publishing

permissions:
  contents: read
  packages: write       # Publish to github Packages

Security Scanning

permissions:
  contents: read
  security-events: write # Upload SARIF results

github Pages Deployment

permissions:
  contents: read
  pages: write          # Deploy to github Pages
  id-token: write       # OIDC for Pages

Troubleshooting github-actions Permission Errors

Step 1: Identify the Required Permissions

Check the action’s documentation or error logs to determine what permissions are needed.

Step 2: Use Minimal Permissions

Start with the least permissions required and add more as needed:

permissions:
  contents: read  # Start here
  # Add more based on your workflow needs

Step 3: Test Locally with github CLI

# Test your token permissions
gh auth status
gh api user

Step 4: Enable Debug Logging

env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

Key Takeaways

Explicit permissions override defaults: When you specify any permission, you must declare all permissions your workflow needs
OIDC requires explicit configuration: Using id-token: write switches to explicit permission mode
Pull request comments need issues: write: PRs are treated as issues in the github API
Start minimal and add incrementally: Begin with basic permissions and expand as needed

Additional Resources

Summary

The “Resource not accessible by integration” error in github-actions is typically caused by insufficient permissions when using explicit permission declarations. The key insight is that specifying any permissions switches github-actions from permissive default mode to explicit permission mode, requiring you to declare all necessary permissions.

This issue commonly occurs when adding OIDC authentication to existing workflows, as the id-token: write permission triggers explicit mode. The solution is to add all required permissions (contents, issues, pull-requests, etc.) alongside your OIDC configuration.

I hope this guide helps you resolve github-actions permission errors quickly and understand the underlying permission model better!