Skip to content

[TEC-554] Document GitHub permissions required by code autofix #2588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abhijna wants to merge 2 commits into
base: main
Choose a base branch
from
+22 −1
Open

[TEC-554] Document GitHub permissions required by code autofix #2588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6c9ae94
api behavior to tech docs
abhijna Apr 16, 2026
587aa66
autofix api permissions
abhijna Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/deployment/deployment-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,10 @@ These features require **read access** to your code.

</details>

:::tip
**Autofix** (Semgrep Code and Semgrep Supply Chain upgrade PRs) needs **Contents: Read and write** on the private app, plus other permissions, so Semgrep can clone and push branches and open draft PRs. For a breakdown of Git operations versus REST endpoints, see [GitHub permissions and API usage for Autofix](/semgrep-code/triage-remediation/autofix#github-permissions-and-api-usage-for-autofix).
:::

</TabItem>

<TabItem value='permissions-gitlab'>
Expand Down
16 changes: 15 additions & 1 deletion docs/semgrep-code/triage-remediation/autofix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Autofix (beta)
description: Use Semgrep Autofix to automatically generate a fix PR for Semgrep Code findings.
description: Use Semgrep Autofix to automatically generate a fix PR for Semgrep Code findings, including required GitHub App permissions and how Semgrep accesses your repository.
tags:
- Semgrep Code
- Semgrep AppSec Platform
Expand Down Expand Up @@ -88,6 +88,20 @@ At this time, Semgrep Memories do not directly influence Autofix PR generation.

Memories may affect PRs indirectly through remediation guidance. If general remediation guidance has been generated and includes information derived from memories, that guidance is passed into the PR generation process. However, memories themselves are not currently sent as direct input when generating the PR.

## GitHub permissions and API usage for Autofix {#github-permissions-and-api-usage-for-autofix}

Autofix uses your **private Semgrep GitHub App** with the permissions below. Use this section for security reviews (for example, which GitHub operations require **Contents: Read and write**).

### Repository permissions

| GitHub App permission | Why Autofix needs it |
| --- | --- |
| **Contents: Read** | Clone the repository over HTTPS (shallow, single-branch) so Semgrep can analyze the code and generate a fix. This uses GitHub’s Smart HTTP Git protocol (`git-upload-pack`). |
| **Contents: Write** | Push the Autofix branch back to the repository. This uses GitHub’s Smart HTTP Git protocol (`git-receive-pack`). |
| **Metadata: Read** | Read repository metadata, including the default branch, using `GET /repos/{owner}/{repo}`. |
| **Pull requests: Write** | Open a **draft** pull request using `POST /repos/{owner}/{repo}/pulls`. |

### How repository contents are accessed

Semgrep does **not** read or write file contents through the REST Contents API (`GET` or `PUT` `/repos/{owner}/{repo}/contents/{path}`). Autofix reads and writes code only through the **Git transport layer** (clone and push), which still requires the GitHub **Contents** permissions above.

3 changes: 3 additions & 0 deletions docs/semgrep-supply-chain/triage-remediation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ To access all upgrade guidance and Autofix features, you must have:
- Semgrep Multimodal [enabled](/semgrep-multimodal/getting-started).
- The **private** GitHub app for Semgrep installed.
- The app must have [**Read and write** access on the **Contents** permission](#grant-read-and-write-access-to-a-private-github-semgrep-app) to open Autofix PRs. Current customers must manually enable this if they haven't already.
- For which GitHub operations and endpoints that entails (Git clone and push versus REST), see [GitHub permissions and API usage for Autofix](/semgrep-code/triage-remediation/autofix#github-permissions-and-api-usage-for-autofix).
- Optionally: if you have [a private registry, connect it to Semgrep](#connect-a-private-registry-to-semgrep) to improve results.

### Features and permissions required
Expand Down Expand Up @@ -161,6 +162,8 @@ To prevent security vulnerabilities from being merged into your codebase, see [S

### Grant **Read and write** access to a private GitHub Semgrep app

Autofix PRs for Supply Chain use the same private GitHub App permissions and GitHub access patterns as [Autofix for Semgrep Code](/semgrep-code/triage-remediation/autofix#github-permissions-and-api-usage-for-autofix).

<GithubAppReadWritePermissions />

### Connect a private registry to Semgrep
Expand Down
Loading