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.

[F-WRunTime]

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://v-api-github-com.adclosenn.dev/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?

[F-WRunTime]

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

[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.

[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
 }