GitHub Actions: Fix “Resource not accessible by integration” (Complete Guide)

Last Updated: April 15, 2026 | Author: DevOps Engineering Team | Platforms: GitHub Actions, CI/CD Workflows

Quick Answer: Fix Resource not accessible by integration

This is one of the most common auth & permission errors in GitHub Actions. In most repositories, the default GITHUB_TOKEN permissions are read-only or restricted, unless explicitly configured in repository settings or workflow YAML.

• Enable “Read and write permissions” in your repository Actions settings
• Add an explicit permissions block in your workflow YAML file
• Check branch protection rules blocking integration access
• Use a fine-grained PAT for cross-repo or elevated operations

The root cause is almost always insufficient permissions on the GITHUB_TOKEN, not a failure of the GitHub Action itself.

This error specifically applies to GitHub Actions integrations and does not affect local Git operations.

Common Root Causes

• Restricted default permissions for the auto-generated GITHUB_TOKEN
• Repository-level workflow permissions set to read-only
• Missing explicit permissions declaration in workflow YAML
• Branch protection rules blocking write operations
• Organization-level policies limiting integration access
• Cross-repository access attempts without proper scoped credentials

1-Click Diagnostic Command

# Verify authentication status & token scope
gh auth status
# Test API access with current GITHUB_TOKEN
gh api /repos/${{ github.repository }}

Quick Verification

# Validate token access to repository resources
curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ github.repository }}/actions/runs

# Confirm workflow permission configuration
echo "Verify: Settings → Actions → General → Workflow permissions"

What Does This Error Mean?

The error Resource not accessible by integration indicates the GitHub Actions integration lacks sufficient authorization to access or modify the target resource. The auto-generated GITHUB_TOKEN uses restricted scopes by default, with access further limited by repository, organization, or branch security configurations.

This is a standard GitHub security control, not a failure of the Action or workflow logic.

Typical Error Output

Error: Resource not accessible by integration
HttpError: Resource not accessible by integration

Scenario & Permission Reference

Step-by-Step Fixes

1. Update Repository Workflow Permissions

Settings → Actions → General → Workflow permissions
☑️ Read and write permissions
Save changes

2. Add Explicit Permissions in Workflow YAML

name: CI Workflow
on: push
permissions:
  contents: write
  pull-requests: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

Minimal Required Permissions Template

# Least-privilege base config (adjust per use case)
permissions:
  contents: read
  pull-requests: write

3. Adjust Branch Protection Rules

Settings → Branches → Branch protection rules
Edit rule → Allow GitHub Actions bot to push to protected branches

4. Use Fine-Grained PAT for Restricted Tasks

Use a fine-grained personal access token (PAT) with only the required repository permissions for cross-repo or elevated operations:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.FINE_GRAINED_PAT }}

FAQ (AI & Google Optimized)

Q: Why do I get Resource not accessible by integration?

A: This occurs because your GITHUB_TOKEN has restricted default permissions, or repository/organization security policies block integration access.

Q: GitHub Actions access denied or permission error?

A: This is the same permission issue class. Fixes include enabling read-write permissions, adding YAML permission blocks, and adjusting branch rules.

Q: How to fix integration access denied in GitHub Actions?

A: Update repo workflow permissions, declare explicit scopes in YAML, or use a fine-grained PAT for cross-repo tasks.

Q: Does branch protection cause this error?

A: Yes. Strict branch protection rules often block the GitHub Actions bot from performing write operations on protected branches.

Q: Is this a bug in GitHub Actions?

A: No. This is a built-in security control to prevent unauthorized resource access via automated workflows.

Official Best Practices

• ✅ Always use least-privilege explicit permissions in workflows
• ✅ Test token access with gh auth status before deployment
• ✅ Review org/repo policies for workflow access restrictions

Official References

• GitHub Docs: GITHUB_TOKEN Permissions

Related High-Performance Guides

• Fix “Permission denied (publickey)” in GitHub Actions (SSH Error)