Missing Checks permission in personal access token

[kemchenj]

Select Topic Area

Bug

Body

There is Checks repository permission that listed in 《Permissions required for fine-grained personal access tokens》

But it is missing in the settings：

I wonder if this is a bug or it is intended?

[froblesmartin]

I have just faced this as well. Curious that, as you mention, it is documented in the fine grained page, but not available. Checking in a GitHub App, it does show it:

[richardsimko]

@kemchenj or @froblesmartin Did you figure out some workaround? Seems to still be an issue.

[PhilipAtCisco]

++ I'm also running into this myself this morning trying to setup some CI tests that create PRs to test a reuseable workflow.

PRs created by bots don't run checks (aws/karpenter-provider-aws#4525) so a fine-grained PAT that is repo scoped I believe is the workaround. I think I could swap back to the regular GITHUB_TOKEN for the validation of the checks, but this missing feature would certainly simplify things!

[richardsimko]

Yeah we're in a similar situation but With Renovate. Had to go back to classic tokens.

[FWBlueWizard]

Also now running into this as well. Started to lose my mind how hard it was to find this related issue. Glad it it's here
++++

[iufor]

I have same issue facing

[andrewlarioza]

We stumble to this issue as well and good to have the resolution soon.
$ curl -L -H "Accept: application/vnd.github+json" -H "Authorization: Bearer github_pat_XXXXX" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/azoiral/devops-test-repo/commits/DEVOPS-3-gatekeeper-v1-3/check-suites { "message": "Resource not accessible by personal access token", "documentation_url": "https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference", "status": "403" }

[andipexton-insight]

To spend hours building a process based on documented functionality that doesn't exist is more than frustrating, it would be nice if someone from @github could give a response? is the error in the documentation or the omission of the feature?

[FWBlueWizard]

Great question. Same problem.

[frankalbenesius]

Just in case anyone else finds this thread, here was a response I got from emailing support:

I apologize for any inconvenience here, but at the moment, it isn't possible to assign Checks permissions to a Fine-grained PAT —only GitHub Apps can access this API. We had that functionality initially, but due to some edge cases we disabled it.

Our engineering team have an issue tracking this and we've added your interest to the issue. In future, we may re-introduce the ability to configure Fine-grained PATs with permissions to run Checks API. When we do publish it, we'll make sure to document it in the GitHub Changelog or the GitHub Blog.

As an alternative I would suggest to make use of the GitHub App to query the required API endpoints. If you're using Actions as your CI, you can authenticate Actions as a GitHub App.

Summary: Use a GitHub App instead of a PAT.

[Lewenhaupt]

Classic tokens also work!

[voodoodror]

Following check-runs classic token modification deprecation https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/#changes-to-check-run-status-modification

Check run status and conclusions can only be updated internally by GitHub Actions.

The documentation says that fine-grained tokens are supported. Thankfully, I found this issue, and it saved me time from debugging it. I wonder why they wrote it in the docs in the first place if they know it's not supported.

[aredridel]

I have a strong suspicion that Copilot wrote the docs and nobody checked. That AI mandate bears this fruit often.

[NedWilbur]

It seems the official API docs are ahead of what is actually supported today...

API Docs - https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28#get-a-check-run

[phenggeler]

It sounds like Github is planning to deprecate classic tokens. The community will need Checks to be supported for fine-grained access tokens before that happens. Would love to see progress on this by Github

[valentjn]

The linked info is about npm classic tokens. Those have indeed been deprecated and in the meantime permanently revoked on December 9, 2025.

GitHub classic PATs are a completely different thing. While GitHub recommends using fine-grained PATs over classic PATs, classic PATs are currently not deprecated since GitHub has a list of limitations of fine-grained PATs they are working on. I think GitHub won't deprecate classic PATs until most of that list has been resolved.

[schpet]

i'm interested in using fine grained tokens to give agents isolated access to repos. but with this limitation they cannot see if the CI checks pass on github actions.

[karszawa]

We are also affected by this limitation. We use fine-grained PATs to give Claude Code (Anthropic's AI coding agent) access to our private organization repositories.

Claude Code's web-based environment (Claude Code on claude.ai) relies on fine-grained PATs for GitHub authentication. In this environment, gh pr view always fails with the statusCheckRollup error because there is no way to grant the Checks permission to the token.

As AI-powered coding agents like Claude Code become more widely adopted, the demand for fine-grained PATs with proper Checks read access is growing rapidly. These agents need to read PR status checks to understand CI results, review PRs effectively, and assist developers in their workflows. The --json workaround exists, but it is not ideal — the default gh pr view experience should just work.

With the planned deprecation of classic PATs, this gap will become a blocker for many teams using AI coding tools in their development workflow.

Environment: gh v2.86.0 on Claude Code Web, fine-grained PAT scoped to an organization's private repository.

[smartcontracts]

Yeah this is a massive blocker for secure Claude Code usage.

[azu]

It seems the Codex App also depends on the Check API via the gh command in the same way, so it appears it can't be used with a Fine-grained PAT.

[EugenMayer]

The above sums it up fairly well. 2 years later the corner cases should have been fixed, shouldnt those?

[davidawad]

I had no clue this was an issue and wasted a good chunk of time and money on it as I thought I could automatically get pull request status via the api. Is there a reason for the limitation?

thanks

[elvisun]

I ended up working around it by hacking my own gh pr checks impl

 # Override gh to fix fine-grained PAT limitation with Checks API
 gh() {
   # Intercept: gh pr checks [PR_NUM] [flags]
   if [[ "$1" == "pr" && "$2" == "checks" ]]; then
     shift 2  # remove "pr checks"
     _gh_pr_checks "$@"
     return $?
   fi
   # Pass through all other gh commands
   command gh "$@"
 }

 _gh_pr_checks() {
   local pr_num="$1"
   local repo
   repo=$(command gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null)

   # If no PR number, get from current branch
   if [[ -z "$pr_num" || "$pr_num" == -* ]]; then
     pr_num=$(command gh pr view --json number -q '.number' 2>/dev/null)
     if [[ -z "$pr_num" ]]; then
       echo "No PR found for current branch" >&2
       return 1
     fi
   fi

   # Get branch from PR
   local branch
   branch=$(command gh api "repos/$repo/pulls/$pr_num" --jq '.head.ref' 2>/dev/null)

   # Get latest workflow run
   local run_data
   run_data=$(command gh api "repos/$repo/actions/runs?branch=$branch&per_page=5" \
     --jq '.workflow_runs | map(select(.event == "pull_request")) | .[0] | {id, name, status, conclusion, html_url}' 2>/dev/null)

   local run_id=$(echo "$run_data" | jq -r '.id')

   if [[ -z "$run_id" || "$run_id" == "null" ]]; then
     echo "No workflow runs found for PR #$pr_num" >&2
     return 1
   fi

   echo "PR #$pr_num ($branch)"
   echo ""

   # Get jobs and format like gh pr checks
   command gh api "repos/$repo/actions/runs/$run_id/jobs" --jq '
     .jobs[] |
     (if .conclusion == "success" then "✓ pass"
      elif .conclusion == "failure" then "X fail"
      elif .conclusion == "skipped" then "- skip"
      elif .status == "in_progress" then "* runs"
      elif .status == "queued" then "- pend"
      else "- " + .status end) + "\t" + .name + "\t" + .html_url
   ' 2>/dev/null | column -t -s $'\t'

   # Return appropriate exit code
   local has_failure=$(command gh api "repos/$repo/actions/runs/$run_id/jobs" --jq '[.jobs[].conclusion] | any(. == "failure")' 2>/dev/null)
   local has_pending=$(command gh api "repos/$repo/actions/runs/$run_id/jobs" --jq '[.jobs[].status] | any(. == "in_progress" or . == "queued")' 2>/dev/null)

   if [[ "$has_failure" == "true" ]]; then
     return 1
   elif [[ "$has_pending" == "true" ]]; then
     return 2
   fi
   return 0
 }

[fipster-dev]

2 years after first report and this is still an issue... how embarrassing!

[dfinlay]

Still an issue, it would be really quite nice if this got resolved. The Checks API already has support for application permissions, so it hopefully shouldn't be too hard to add it to the Fine Grained PAT permission builder. (Assuming the documentation is correct and the API endpoints already support fine grained PAT and just the permission builder is missing the functionality). Technically the Checks API docs may be correct, but then you've locked the Checks API in a manner that is impossible to make a functional key for.

Mismatched API Docs

The Checks API Documentation for Create a Check Run

and Get a Check Run state that fine grained access PATs work with the Check API.

However the PAT limitation documentation says that calling Check API is a known gap. So there is a contradiction here, either the limitation is in the Checks API¹ OR it's simply in the fine grained permission builder.

Footnotes

1. If the Checks API doesn't support fine grained PATs, it would make sense that the permission builder doesn't include it. But it claims to. ↩