[TEC-629] GitHub PAT permissions docs re-worked - #2805
Open
abhijna wants to merge 3 commits into
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
abhijna
marked this pull request as draft
August 22, 2026 00:23
abhijna
marked this pull request as ready for review
August 28, 2026 18:29
armchairlinguist
requested changes
Aug 31, 2026
armchairlinguist
left a comment
armchairlinguist
left a comment
Collaborator
There was a problem hiding this comment.
This definitely needs some refinement - while I've flagged a few things I noticed, I would highly recommend checking this with an SCM SME from the platform team.
| <Note> | ||
| **Managed Scans on GitHub** | ||
|
|
||
| [Semgrep Managed Scans](/deployment/managed-scanning/github) for GitHub still require the public and private Semgrep GitHub Apps. A PAT alone does not replace those apps for Managed Scans. |
Collaborator
There was a problem hiding this comment.
It does, though.
| [Semgrep Managed Scans](/deployment/managed-scanning/github) for GitHub still require the public and private Semgrep GitHub Apps. A PAT alone does not replace those apps for Managed Scans. | ||
| </Note> | ||
|
|
||
| Use a personal access token (PAT) when your organization connects GitHub to Semgrep with a token instead of a GitHub App, or alongside a GitHub App. Semgrep recommends a **fine-grained** PAT. **Classic** PATs remain supported when org policy requires them. |
Collaborator
There was a problem hiding this comment.
We don't do combined connections AFAIK?
|
|
||
| Use a personal access token (PAT) when your organization connects GitHub to Semgrep with a token instead of a GitHub App, or alongside a GitHub App. Semgrep recommends a **fine-grained** PAT. **Classic** PATs remain supported when org policy requires them. | ||
|
|
||
| A PAT can only grant access that the creating GitHub user already has. Use a dedicated machine user when possible. That user must be a member of the target organization, or a collaborator on the selected repositories. For [Autofix](/semgrep-code/triage-remediation/autofix), the user must be able to push branches and open pull requests on those repositories. |
Collaborator
There was a problem hiding this comment.
Is "dedicated machine user" the term GitHub uses?
| - Have connected to a GitHub org already, but want to add additional GitHub connections | ||
|
|
||
| You can connect to GitHub using Semgrep's GitHub app and one of the following: a personal access token or your individual GitHub account. | ||
| You can connect to GitHub using Semgrep's GitHub app and one of the following: a personal access token or your individual GitHub account. If you use a personal access token, see [GitHub personal access tokens](/deployment/prepare/scm-permissions#github-personal-access-tokens) for required roles and scopes. |
Collaborator
There was a problem hiding this comment.
I'm not sure what this was meant to mean or what it means now - again, I don't think we really do combined connection types.
| </Step> | ||
| <Step> | ||
| Under **Repository permissions**, set **Pull requests** to **Read and write**. | ||
| Under **Repository permissions**, set **Pull requests** to **Read and write** if you use Autofix. For read-only code access, you can leave **Pull requests** at **No access**. |
Collaborator
There was a problem hiding this comment.
Is this actually true? Don't we need access to them to write PR comments?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR updates the GitHub permissions docs so PAT users (including orgs still on classic tokens) can see what scopes and roles they need.
Reorg
Review focus: Are the classic vs fine-grained scopes right for connection validation, and does the public/private App + PAT layout make sense?