Fix GitHub Actions 'Resource not accessible by integration'

The Error

A GitHub Actions workflow step fails with:

Error: Resource not accessible by integration

This typically appears when a step tries to create a release, push a package, comment on a PR, or modify repository contents using the built-in GITHUB_TOKEN.

Root Cause

GitHub Actions provides an automatic GITHUB_TOKEN for each workflow run. This token's permissions are controlled at three levels:

1. Organization/repository default permissions - Admins can restrict the default token to read-only.
2. Workflow-level permissions block - When present, it overrides defaults and grants only what is explicitly listed.
3. Job-level permissions block - Overrides the workflow-level block for that specific job.

The error occurs when the token lacks the specific permission needed for the API call. Since GitHub tightened defaults in 2023, many repositories now default to read-only tokens.

Step-by-Step Fix

1. Identify what permission is needed

Check the failing step's documentation. Common mappings:

Action	Required permission
Create a release	contents: write
Comment on a PR	pull-requests: write
Push a package	packages: write
Update commit status	statuses: write
Modify issues	issues: write
Push to the repo	contents: write

2. Add permissions to the workflow file

Add a permissions block at the workflow or job level:

name: Release

on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

If multiple permissions are needed:

permissions:
  contents: write
  pull-requests: write
  packages: write

3. Check repository-level settings

Go to Settings > Actions > General > Workflow permissions in your repository. Ensure it is set to "Read and write permissions" or that your explicit permissions block covers what you need.

For organization-managed repos:

Organization Settings > Actions > General > Workflow permissions

4. Handle fork-based pull requests

Workflows triggered by pull_request from forks always receive a read-only token regardless of your permissions block. This is a GitHub security restriction. For fork PRs, use pull_request_target instead (with caution):

on:
  pull_request_target:
    types: [opened, synchronize]

Warning: pull_request_target runs with the base branch's code and full write access. Never check out and execute untrusted fork code with this trigger.

5. If using a Personal Access Token (PAT) instead

When GITHUB_TOKEN is insufficient (cross-repo access, triggering other workflows), use a PAT or GitHub App token:

steps:
  - uses: actions/checkout@v4
    with:
      token: ${{ secrets.MY_PAT }}

Prevention Tips

• Always declare permissions explicitly. Do not rely on repository defaults. Explicit permissions make workflows portable and self-documenting.
• Follow the principle of least privilege. Only grant the permissions each job actually needs. Use job-level blocks if different jobs need different scopes.
• Audit workflows after enabling restrictive defaults. When switching an org to read-only defaults, test all existing workflows to catch breakages.
• Use GitHub Apps over PATs. App tokens offer fine-grained permissions, are scoped to specific repositories, and do not depend on a single user account.