Fine-grained GitHub PAT w/ documented permissions fails with `Unable to check pull mergeable status`.

[TonyLovesDevOps]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request. Searching for pre-existing feature requests helps us consolidate datapoints for identical requirements into a single place, thank you!
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.

---

Overview of the Issue

The Atlantis docs for GitHub credentials (specifically: https://www.runatlantis.io/docs/access-credentials.html#github-user) imply that a GitHub “user token” works with the documented minimal permissions. In practice, GitHub fine-grained personal access tokens (FG-PATs) can be unable to access the GitHub API surfaces Atlantis uses for PR status/mergeability checks—particularly around branch protection and checks/check-runs—even when the token is granted Repository Administration: read and other suggested repo permissions.

Result: Atlantis 0.40.0 fails to fetch its PR “status bundle” during apply, logs:

fetching rulesets, branch protections and status checks from GraphQL: Resource not accessible by personal access token

…and then assumes approved=false / mergeable=false, which blocks apply when apply_requirements includes approved/undiverged.

This seems to be a known issue with fine-grained PATs

I’m attaching screenshots showing:

• the token’s configured repo/org permissions
• the org’s fine-grained PAT policy settings

Reproduction Steps

1. Deploy Atlantis v0.40.0 configured with GitHub user token auth, and enable repo config with:
   • apply_requirements: [approved, undiverged]
2. Use a fine-grained PAT scoped to the repo(s), with repository permissions including:
   • Contents: Read
   • Pull requests: Read and write
   • Commit statuses: Read and write
   • Administration: Read-only
   • Metadata: Read-only (required)
   • (Optional) org permissions: Members read (if you use team-based restrictions)
3. Trigger atlantis apply on a PR.

Observed:

• Atlantis logs show it cannot fetch “rulesets, branch protections and status checks from GraphQL” due to PAT access restrictions.
• Atlantis then assumes approved/mergeable are false and blocks apply when requirements include approved/undiverged.

Expected:

• With the permissions suggested by docs (and/or with Administration read for protections), Atlantis should be able to evaluate approved and undiverged reliably using a fine-grained PAT, or the docs should clearly state FG-PATs are not sufficient and that a GitHub App or classic PAT is required.

Logs

Logs

{"level":"error","ts":"2026-03-02T19:13:06.542Z","caller":"common/instrumented_client.go:140","msg":"Unable to check pull mergeable status, error: getting pull request status: fetching rulesets, branch protections and status checks from GraphQL: Resource not accessible by personal access token","json":{"repo":"redacted-org/redacted-repo","pull":"<PR_NUM>"}}
{"level":"warn","ts":"2026-03-02T19:13:06.542Z","caller":"events/apply_command_runner.go:115","msg":"unable to get pull request status: fetching mergeability status for repo: redacted-org/redacted-repo, and pull number: <PR_NUM>: getting pull request status: fetching rulesets, branch protections and status checks from GraphQL: Resource not accessible by personal access token. Continuing with mergeable and approved assumed false","json":{"repo":"redacted-org/redacted-repo","pull":"<PR_NUM>"}}
{"level":"error","ts":"2026-03-02T19:13:07.802Z","caller":"events/instrumented_project_command_runner.go:87","msg":"Failure running apply operation: Pull request must be approved according to the project's approval rules before running apply.","json":{"repo":"redacted-org/redacted-repo","pull":"<PR_NUM>"}}```

Environment details

Environment details
• Atlantis version: 0.40.0 (commit: 5d45b24) (build date: 2026-02-26T21:24:12Z)
• Deployment method: https://github.com/terraform-aws-modules/terraform-aws-atlantis
• If not running the latest Atlantis version have you tried to reproduce this issue on the latest version: yes (0.40.0)
• Atlantis flags:

Atlantis server-side config file:

version: 3
automerge: false
fail-on-pre-workflow-hook-error: true
repos:
  - id: github.com/redacted-org/redacted-repo
    branch: /main/
    plan_requirements: [undiverged]
    apply_requirements: [approved, undiverged]
    import_requirements: [approved, undiverged]
    workflow: terragrunt
    pre_workflow_hooks:
      [
        {
          "run": 'terragrunt-atlantis-config generate --output atlantis.yaml --parallel --create-workspace --autoplan 2>&1 | tee "$DIR/pre-workflow-hooks.log"',
          "shellArgs": "-ceuo pipefail",
        },
        {
          "run": 'gpg --import /PUBLIC_KEY_BLOCK 2>&1 | tee -a "$DIR/pre-workflow-hooks.log"',
          "shellArgs": "-ceuo pipefail",
        },
        {
          "run": 'gpg --import-ownertrust /KEY_TRUST 2>&1 | tee -a "$DIR/pre-workflow-hooks.log"',
          "shellArgs": "-ceuo pipefail",
        },
        {
          "run": 'git config --global --add safe.directory ''*'' 2>&1 | tee -a "$DIR/pre-workflow-hooks.log"',
          "shellArgs": "-ceuo pipefail",
        },
      ]
workflows:
  terragrunt:
    env:
      TG_TF_PATH: "/usr/bin/terraform"
      TF_IN_AUTOMATION: "true"
      TG_NON_INTERACTIVE: "true"
      TG_TF_FORWARD_STDOUT: "true"
    plan:
      steps:
        - run: /verify-commits
        - run: /ensure-refs-on-main
        - run: /verify-providers
        - run: yes | terragrunt plan -out=$PLANFILE
    apply:
      steps:
        - run: /verify-commits
        - run: /ensure-refs-on-main
        - run: /verify-providers
        - run: terragrunt apply $PLANFILE
        - run: /update-parameter

Repo atlantis.yaml file:

N/A

Any other information you can provide about the environment/deployment (efs/nfs, aws/gcp, k8s/fargate, etc)
--->

Additional Context

GitHub UI screenshots attached showing the fine-grained PAT’s configured repo/org permissions and the org’s fine-grained PAT policy settings.

GitHub returns 403 “Resource not accessible by personal access token” for branch protection and checks endpoints even when X-Accepted-Github-Permissions indicates the token should have the correct permission.
Related GitHub community discussion suggesting FG-PAT limitations around “Checks” in some contexts: GitHub Discussion

Docs request: Please update the GitHub credentials docs to clearly state that fine-grained PATs may not be sufficient for Atlantis when using apply_requirements like approved/undiverged (and/or when Atlantis needs to read branch protection and checks), and recommend using a GitHub App (preferred) or a classic PAT instead. Also helpful: list the exact GitHub App permissions required for Atlantis.

[dosubot]

Hi @TonyLovesDevOps! I'm Dosu and I’m helping the atlantis team.

This is a known limitation. Atlantis uses a GraphQL query to fetch rulesets, branch protections, and status checks for mergeability checks. Fine-grained PATs have limited access to these GraphQL endpoints, even with the correct REST API permissions configured.

When the GraphQL query fails with "Resource not accessible by personal access token", Atlantis defaults to approved=false and mergeable=false, which blocks apply when using apply_requirements: [approved, undiverged].

Recommended solution: Use a GitHub App instead of a fine-grained PAT. GitHub Apps have more reliable access to the GraphQL endpoints Atlantis needs. The required GitHub App permissions are:

Permission	Access Level
Administration	Read-only
Checks	Read and write
Commit statuses	Read and write
Contents	Read and write
Issues	Read and write
Metadata	Read-only
Pull requests	Read and write
Webhooks	Read and write
Members	Read-only
Actions	Read-only

Note: The Actions permission (added in v0.30.0) is specifically needed for checking workflow requirements in rulesets.

If you must use a PAT, a classic PAT with the repo scope may work better than a fine-grained PAT, though GitHub Apps remain the recommended approach for production.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[TonyLovesDevOps]

@dosu We do not wish to grant Read and write permissions to Contents (and some others) which is specifically why we are trying to use a fine-grained PAT. This limitation should at least be made very clear in the docs, as fine-grained PATs are basically unusable.

[dosubot]

You raise a valid concern. Looking at the Atlantis codebase, Atlantis only performs read operations on repository contents (fetching files, cloning). The Contents: Read and write requirement in the current docs appears to be driven by specific features like fork operations (e.g., atlantis testdrive) rather than core plan/apply functionality.

For your use case with apply_requirements: [approved, undiverged], the blocker is specifically the GraphQL API access for branch protections and rulesets—not the Contents permission. Fine-grained PATs have limited access to these GraphQL endpoints regardless of what permissions you grant.

I agree the docs should be clearer about:

1. Fine-grained PATs being insufficient for apply_requirements checks that need branch protection/ruleset data
2. Which specific features actually require Contents: Read and write vs read-only

If you want to pursue a minimal-permissions setup, a GitHub App with Contents: Read only might work for basic plan/apply if you're not using features that require write access (like auto-merging or forking)—though this isn't officially documented or tested. The GraphQL access for mergeability checks would still work better with a GitHub App than a fine-grained PAT.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}