Enable source code manager code access

Some Semgrep features, including Semgrep Managed Scans, Semgrep Multimodal, and Autofix, require Semgrep to read repository contents.

Grant code access by assigning additional scopes to the access token or GitHub App that facilitates communication between Semgrep and your source code manager (SCM).

Other SCM permissions

This page covers code read and write access only. For PR or MR comments, GitHub App installation, sign-in scopes, and other requirements, see SCM permissions.

The following table shows the minimum scopes required for each SCM.

SCM	Read access scope	Write access scope
Azure DevOps	Code (read)	Code (read and write)
Bitbucket Cloud	repository:read pullrequest:read	repository:write pullrequest:write
Bitbucket Data Center	repository:read	repository:write
GitHub.com and GitHub Enterprise Server	contents:read	contents:write
GitLab and GitLab Self-Managed	read_repository	write_repository

Grant code access to Semgrep with a private GitHub app

If you are an existing Semgrep user and your private Semgrep GitHub app does not have code access enabled, follow these steps to update the app and grant code access to Semgrep.

GitHub grants code access through Repository permissions > Contents under Developer Settings. The installation page at Settings > Applications might list read/write permissions but those do not enable file access.

APP SLUG

To find the name of your app slug in Semgrep AppSec Platform:

1. Go to Settings > Source code managers.
2. Find the panel for your source code manager. The app slug is listed immediately following the name of the source code manager.

1. In GitHub, navigate to Settings > Developer Settings. You should see your Semgrep App listed in the GitHub Apps tab. GitHub Enterprise Server users must replace the https://github.com base URL with the base URL of their GitHub Enterprise Server instance.

2. Click Edit on the Semgrep app.

3. Navigate to the Permissions and events section.

4. Expand Repository permissions and go to Contents.

5. Click the drop-down menu and select Read and write. Read and write is required for Autofix PRs. If you only need Semgrep to read repository contents, select Read instead.

6. Click Save Changes.

7. GitHub might send you or your GitHub admin an email to approve the permission changes.

8. Navigate back to the main GitHub Settings page. One way to do so is by clicking Settings in GitHub’s website breadcrumbs.

9. In the Applications tab, locate the Semgrep app under the Installed GitHub Apps tab.

10. Click Review request next to the Permission updates requested message, then choose Accept new permissions.

Once approved, Semgrep has code access to your GitHub repositories.

Grant code access to Semgrep for token-based SCM connections

If you onboarded your repositories using an access token, follow these steps to grant code access to Semgrep.

Azure DevOps Cloud

Before creating or updating the Azure DevOps PAT, ensure that the account used to create the token has access to the Azure DevOps projects and repositories Semgrep scans.

A PAT can only grant access that the account already has. Microsoft requires at least Basic access for accounts that contribute to code. To create Autofix PRs, the account must also be able to read repository contents, create branches, push commits, and create PRs at the repository level.

Grant project and repository access

1. In Azure DevOps, navigate to your organization: https://dev.azure.com/ORGANIZATION_NAME

2. Go to Organization settings > Users

3. Find the account used for your Semgrep Azure DevOps connection. If the account is not listed, click Add users and add the account to the organization.

4. Set the account’s Access level to Basic. Stakeholder access does not allow code contribution in private projects.

5. Ensure the account is a member of the Azure DevOps project that contains the repositories Semgrep scans. If you use Option 1 below, adding the account to Contributors also adds project membership.

Grant the account repository access using one of the following options.

Option 1: Add the account to the Project Contributors group

Use this option to grant the account standard contributor access across the project.

1. Go to Project settings > Permissions

2. Select Contributors.

3. Click Members.

4. Add the account used for the Semgrep Azure DevOps connection.

Option 2: Grant access to specific repositories

Use this option to restrict Semgrep access to specific repositories.

1. Go to Project settings > Repositories

2. Select the repository that Semgrep scans.

3. Go to the Security tab.

4. Search for the account used for the Semgrep Azure DevOps connection.

5. Set the following permissions to Allow:

   • Read
   • Contribute
   • Create branch
   • Contribute to pull requests
6. Repeat these steps for each repository that Semgrep scans.

Branch-specific permissions

Branch permissions can override repository permissions. If the target repository uses branch-specific permissions, confirm that the Semgrep account is not denied access on the target branch. The account must be able to contribute to branches it creates and create PRs into the repository’s default branch.

Create and configure an access token

1. Navigate to the Azure DevOps access token settings page: https://dev.azure.com/ORGANIZATION_NAME/_usersSettings/tokens.

2. Click New token to open the Create a new personal access token dialog.

3. Assign the Code (read and write) scope to the token. This scope includes read access and the ability to create and manage PRs. For read-only code access, assign Code (read) instead.

   Also assign any other scopes your deployment needs, such as those listed in the Autofix row of SCM permissions.

4. Create the token, and copy its value. Azure DevOps only shows the token value once.

5. Return to Semgrep AppSec Platform, and go to Settings > Source code managers.

6. Find the connection associated with your organization, and click Update access token.

7. Paste in your new access token.

8. Click Save.

Once saved, Semgrep has code access to your Azure DevOps repositories.

Bitbucket Cloud

Bitbucket Cloud access tokens are tied to a workspace, project, or repository, not to an individual user account. Create the token at the narrowest level that includes the repositories Semgrep scans.

Branch permissions can restrict who can push or merge code. If you grant write access for features such as Autofix PRs, ensure that the access token can push branches and create PRs into the target branch.

1. Navigate to the Bitbucket Cloud access token settings page: https://bitbucket.org/WORKSPACE/workspace/settings/access-keys.

2. Create a new access token.

3. Assign the repository:read, pullrequest:read, repository:write, and pullrequest:write scopes to the token, along with any other scopes your deployment needs.

4. Copy the token’s value.

5. Return to Semgrep AppSec Platform, and go to Settings > Source code managers.

6. Find the Bitbucket connection associated with your workspace, and click Update access token.

7. Paste in your new access token.

8. Click Save.

Once saved, Semgrep has code access to your Bitbucket Cloud repositories.

Bitbucket Data Center

Bitbucket Data Center HTTP access tokens can be created for a user, project, or repository. Create the token at the narrowest level that includes the repositories Semgrep scans.

Branch permissions can restrict who can push or merge code. If you grant write access for features such as Autofix PRs, ensure that the HTTP access token can push branches and create PRs into the target branch.

1. See Bitbucket Data Center HTTP access token requirements to create a token with the permissions your deployment needs, including repository read and write access. Copy the token’s value.

2. Return to Semgrep AppSec Platform, and go to Settings > Source code managers.

3. Find the Bitbucket Data Center connection associated with your instance, and click Update access token.

4. Paste in your new access token.

5. Click Save.

Once saved, Semgrep has code access to your Bitbucket Data Center repositories.

GitHub

Use these steps to create a GitHub fine-grained personal access token with code access and add it to Semgrep.

Organization approval

Some GitHub organizations require approval for fine-grained personal access tokens. If your organization requires approval, an organization owner must approve the token before Semgrep can use it.

1. Navigate to the GitHub personal access token settings page: https://github.com/settings/personal-access-tokens. GitHub Enterprise Server users must replace the https://github.com base URL with the base URL of their GitHub Enterprise Server instance.

2. Click Generate new token.

3. Enter a name for the token and set an expiration date according to your organization’s token rotation policy.

4. Under Resource owner, select the GitHub organization that contains the repositories Semgrep scans.

5. Under Repository access, select either All repositories or Only select repositories. If you choose Only select repositories, select the repositories that this token is used with.

6. Under Repository permissions, set Contents to Read and write.

   Read and write is required for Autofix PRs. If you only need Semgrep to read repository contents, select Read-only instead.

7. Under Repository permissions, set Pull requests to Read and write.

8. Click Generate token and copy its value.

9. Return to Semgrep AppSec Platform, and go to Settings > Source code managers.

10. Find the GitHub connection associated with your organization, and click Update access token.

11. Paste in your new access token.

12. Click Save.

Once saved, Semgrep has code access to your GitHub repositories.

GitLab

GitLab access tokens can be created for a user, group, or project. Create the token at the narrowest level that includes the repositories Semgrep scans. Project access tokens are scoped to a single project. Group access tokens are scoped to a group and its projects.

Protected branches can restrict who can push or merge code. If you grant write access for features such as Autofix PRs, ensure that the access token can push branches and create merge requests into the target branch.

1. Navigate to the GitLab access token settings page: https://gitlab.com/groups/GROUP/-/settings/access_tokens.

   GitLab Self-Managed users must replace the https://gitlab.com base URL with the base URL of the GitLab Self-Managed instance.

2. Create a new access token.

3. Assign the token the read_repository and write_repository scopes, along with any other scopes your deployment needs.

   The write_repository scope is required for Autofix PRs. If you only need Semgrep to read repository contents, assign read_repository instead.

4. Copy the token’s value.

   GitLab only shows the token value once.

5. Return to Semgrep AppSec Platform, and go to Settings > Source code managers.

6. Find the GitLab connection associated with your group, and click Update access token.

7. Paste in your new access token.

8. Click Save.

Once saved, Semgrep has code access to your GitLab repositories.