GitHub Actions Cannot Create a Deployment - Missing deployments: write

By Daniel Zoghalchali·Latchkey

A workflow that creates a GitHub Deployment or updates a deployment status gets a 403 because the token defaults to read-only and lacks deployments: write.

What this error means

A step calling the deployments API (or an action that creates deployment statuses) fails with a 403 / "Resource not accessible by integration" for the deployment.

HttpError: Resource not accessible by integration
  status: 403
  request to POST /repos/org/repo/deployments

Common causes

Token lacks deployments: write

Creating deployments or deployment statuses requires deployments: write. With the read-only default, the API call is denied.

Confusing deployments with environments

The deployments API permission is separate from environment protection rules. You can have environment access but still lack deployments: write for the API call.

How to fix it

Grant deployments: write

Add the deployments write scope to the job that creates deployments or statuses.

permissions:
  deployments: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: gh api repos/${{ github.repository }}/deployments -f ref=main
        env: { GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} }

Use the right scope per action

1. Grant deployments: write only on jobs that call the deployments API.
2. Keep environment protection (environment:) separate from API permissions.
3. Use a least-privilege permissions block rather than write-all.

How to prevent it

• Declare deployments: write on jobs using the deployments API.
• Distinguish API permissions from environment protection rules.
• Prefer least-privilege scoped permissions blocks.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions