Skip to content
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

Update connect scm instructions and improve readability #1970

Merged
merged 5 commits into from
Feb 13, 2025
Merged

Update connect scm instructions and improve readability #1970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
098acb8
begin rearranging docs
s-santillan Feb 12, 2025
56b0ab7
update steps and screenshots
s-santillan Feb 13, 2025
9a3807c
remove headers, add br to image
s-santillan Feb 13, 2025
e3f1e35
update header max frontmatter
s-santillan Feb 13, 2025
0a8e24a
Merge branch 'main' into sara/tec-203-outdated-scm-tab-screenshot
s-santillan Feb 13, 2025
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
139 changes: 89 additions & 50 deletions docs/deployment/connect-scm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,15 @@ slug: connect-scm
title: Connect a source code manager
hide_title: true
description: Connect a source code manager for use with Semgrep.
toc_max_heading_level: 3
toc_max_heading_level: 2
tags:
- Deployment
- Semgrep AppSec Platform
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Connect a source code manager

:::note Your deployment journey
Expand All @@ -33,38 +36,48 @@ The process to connect a source code manager depends on whether your SCM tool is

If you opted to scan a GitHub or GitLab repository when you initially signed in, you may have already performed these steps and can skip to [Next steps](#next-steps).

### Azure DevOps Cloud

1. Sign in to Semgrep AppSec Platform.
1. On the sidebar, click the account name to open the drop-down menu.
1. Using the drop-down menu, select the account you want to make a connection for.
1. Go to **Settings** > **Source Code Managers**, and click **Add Azure DevOps**.
![Source code manager tab](/img/source-code-manager.png#md-width)
<Tabs
defaultValue="github-cloud"
values={[
{label: 'Azure DevOps Cloud', value: 'azure-devops-cloud'},
{label: 'Bitbucket Cloud', value: 'bitbucket-cloud'},
{label: 'GitHub Cloud', value: 'github-cloud'},
{label: 'GitLab Cloud', value: 'gitlab-cloud'},
]}
>

<TabItem value='azure-devops-cloud'>

1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
s-santillan marked this conversation as resolved.
Show resolved Hide resolved
1. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers > Add > Azure DevOps**.
1. In the **Connect your Azure DevOps organization** dialog box, provide:
- The **Name of your Azure DevOps organization**
- Your **Access token**. See [User personal access tokens](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) for information on generating a token.
2. Click **Connect** to save and proceed.
3. The Azure DevOps organization is now listed under **Source Code managers**. Click **Test connection** to verify that the new integration is installed correctly.
3. The Azure DevOps organization is now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.

### Bitbucket Cloud
</TabItem>
<TabItem value='bitbucket-cloud'>

1. Sign in to Semgrep AppSec Platform.
1. On the sidebar, click the account name to open the drop-down menu.
1. Using the drop-down menu, select the account you want to make a connection for.
1. Go to **Settings** > **Source Code Managers**, and click **Add Bitbucket Cloud**.
![Source code manager tab](/img/source-code-manager.png#md-width)
1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
1. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers > Add > Bitbucket Cloud**.
1. In the **Connect your Bitbucket Workspace** dialog box, provide:
- The **Name of your Bitbucket Workspace**
- Your **Access token**. Semgrep expects a [workspace-level access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/).
1. Click **Connect** to save and proceed.
1. The Bitbucket project is now listed under **Source Code organizations**. Click **Test connection** to verify that the new integration is installed correctly.
1. The Bitbucket project is now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.

### GitHub Cloud
</TabItem>
<TabItem value='github-cloud'>

1. Sign in to Semgrep AppSec Platform.
1. On the sidebar, click **the organization account** you want to make a connection for.
1. Click **Settings** > **Source Code Managers**.
![Source code manager tab](/img/source-code-manager.png#md-width)
1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
1. From the **Navigation bar**, click **<i class="fa-solid fa-gear"></i> Settings > Source code managers**.
1. Click **Connect to GitHub**.
1. Review the permissions requested by Semgrep, then click **Continue**.
1. Click the organization you want to install Semgrep on.
Expand All @@ -73,6 +86,7 @@ If you opted to scan a GitHub or GitLab repository when you initially signed in,
1. After a successful link, you are signed out of Semgrep AppSec Platform automatically, as your credentials have changed after linking an organization.
1. Sign back in to Semgrep AppSec Platform.

</TabItem>

<!-- removed temporarily because we're using the "old flow"
:::tip
Expand All @@ -82,32 +96,49 @@ If you opted to scan a GitHub or GitLab repository when you initially signed in,

-->

You have successfully connected an org in Semgrep AppSec Platform with an organization in your source code management tool.

### GitLab Cloud
<TabItem value='gitlab-cloud'>

1. Create a PAT by following the steps outlined in this [guide to creating a PAT](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). Ensure that the PAT is created with the required `api` scope.
1. Sign in to [Semgrep AppSec Platform](https://semgrep.dev/login).
1. Click **<i class="fa-solid fa-gear"></i> Settings > Source Code Managers > Add GitLab Cloud** and enter the personal access token generated into the **Access token** field.
1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
1. Click **<i class="fa-solid fa-gear"></i> Settings > Source Code Managers > Add > GitLab Cloud**
1. Enter the personal access token generated into the **Access token** field.
1. Enter your GitLab group's name into the **Name of your GitLab Group** field. If your repositories are organized in subgroups, you only need to provide the name of the top-level group.
1. Optional, but recommended: if you have multiple GitLab groups in your GitLab account, create a source code manager per group. Repeat steps 1, 3-4 for each GitLab group.
1. The GitLab groups are now listed under **Source code managers**. Click **Test connection** to verify that the new integration is configured correctly.
1. The GitLab groups are now listed under **Source code managers**. Click **Test** to verify that the new integration is configured correctly.

## Connect to on-premise orgs and projects
You have successfully connected an org in Semgrep AppSec Platform with an organization in your source code management tool.

</TabItem>
</Tabs>

### Bitbucket Data Center
## Connect to on-premise orgs and projects

1. Sign in to Semgrep AppSec Platform.
1. Go to **Settings** > **Source Code Managers**, and click **Add Bitbucket Data Center**.
![Source code manager tab](/img/source-code-manager.png#md-width)
<Tabs
defaultValue="github-enterprise"
values={[
{label: 'Bitbucket Data Center', value: 'bitbucket-data-center'},
{label: 'GitHub Enterprise Server', value: 'github-enterprise'},
{label: 'GitLab Self-Managed', value: 'gitlab-sm'},
]}
>

<TabItem value='bitbucket-data-center'>

1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
1. Go to **<i class="fa-solid fa-gear"></i> Settings** > **Source code managers**, and click **Add > Bitbucket Data Center**.
1. In the **Connect your Bitbucket project (key)** dialog box, provide:
- The **Name of your Bitbucket project (key)**. This must be the project key, which you can find by navigating to `<YOUR_BITBUCKET_DATA_CENTER_BASE_URL>/projects`.
- The **URL** to access your installation of Bitbucket Data Center
- The **Access Token** that [grants Semgrep permission to communicate with your project](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Semgrep expects a [workspace-level access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/)
2. Click **Connect** to save and proceed.
3. The Bitbucket project is now listed under **Source Code organizations**. Click **Test connection** to verify that the new integration was installed correctly.
3. The Bitbucket project is now listed under **Source code managers**. Click **Test** to verify that the new integration was installed correctly.

### GitHub Enterprise Server
</TabItem>
<TabItem value='github-enterprise'>

This section is applicable to users on a **GitHub Enterprise Server** plan.

Expand All @@ -118,12 +149,16 @@ and orgs in your GHE deployment. There are two primary installation steps:
that "owns" the app.
2. Install the app for additional GHE orgs.

#### Initial Semgrep App installation
### Initial Semgrep App installation

If your deployment contains many orgs, you must choose an org in the deployment that acts as the **owner** of the Semgrep App. As the owner, this org controls the settings and permissions granted to the app.
If your deployment contains many orgs, you must **choose an org** among your accounts that acts as the **owner** of the Semgrep App. As the owner, this org controls the settings and permissions granted to the app.

1. Log in to [Semgrep AppSec Platform](https://semgrep.dev/login/).
2. Click **<i class="fa-solid fa-gear"></i> Settings** > **Source Code Managers**, and click **Add GitHub Enterprise**.
Ensure that you have selected the intended owner by viewing the account name in the navigation bar:
<img src="/docs/img/more-accounts-dropdown.png" height="350px" /><br />
Choose another account by clicking the **account name** and selecting an account from the drop-down box. Then, perform the following steps to set up the connection:

1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login/).
2. Click **<i class="fa-solid fa-gear"></i> Settings** > **Source code managers > Add > GitHub Enterprise**.
3. In the **Connect your GitHub Organization** dialog box, provide:
- The **Name of your GitHub Organization**
- The **URL** to access your deployment
Expand All @@ -139,7 +174,7 @@ If your deployment contains many orgs, you must choose an org in the deployment
11. After you name your app, choose the GHE org to which you want it installed.
12. Select the org that you want to act as the owner of the app, and click **Install**.
13. Wait for the installation to complete. When done, you will be redirected to Semgrep.
14. Verify the installation by navigating to **Settings** > **Source Code Managers**. Ensure that the entry for your SCM shows a **Connected** badge.
14. Verify the installation by navigating to **Settings** > **Source code managers**. Ensure that the entry for your SCM shows a **Connected** badge.
15. In GHE, you should see the app listed as installed on the **GitHub Apps** page.
![GHE showing installed Semgrep App](/img/ghe-9.png#md-width)
You can click **Configure** to choose the repositories to which the app has access. Additionally, you can go to **App settings** to customize the permissions granted to the app.
Expand All @@ -150,7 +185,7 @@ At this point, you've successfully installed the GHE Semgrep App on the owner GH

![App installation page](/img/ghe-11.png#md-width)

#### Install the app for subsequent GHE orgs
### Install the app for subsequent GHE orgs

You can install the Semgrep app onto additional GHE orgs at any time. To do so:

Expand All @@ -160,27 +195,31 @@ You can install the Semgrep app onto additional GHE orgs at any time. To do so:
![Org list](/img/ghe-13.png#md-width)
3. In the popup confirmation message, click **Install**.
![GitHub installation prompt](/img/ghe-14.png#md-width)
4. The GHE org should now be listed under **Source code organizations**.
![Source code organizations list](/img/ghe-15.png#md-width)
4. The GHE org should now be listed under **Source code managers**.

You have successfully connected Semgrep to your GitHub Enterprise Server.

### GitLab Self-Managed Plans
</TabItem>
<TabItem value='gitlab-sm'>

This section is applicable to users with subscriptions to any **GitLab self-managed plan**.

Connect Semgrep and GitLab Self-Managed accounts by creating a PAT and providing it to Semgrep using Semgrep AppSec Platform:

1. Create a PAT by following the steps outlined in this [guide to creating a PAT](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). Ensure that the PAT is created with the required `api` scope.
2. Sign in to [Semgrep AppSec Platform](https://semgrep.dev/login).
3. Click **<i class="fa-solid fa-gear"></i> Settings > Source Code Managers > Add GitLab Self-Managed** and enter the personal access token generated into the **Access token** field.
4. Enter your GLSM base URL into the **URL** field.
5. Enter your GitLab group's name into the **Name of your GitLab Group** field. If your repositories are organized in subgroups, you only need to provide the name of the top-level group.
6. If you have multiple GitLab groups in your GitLab account, you need to create a source code manager per group. Repeat steps 1, 3-5 for each GitLab group.
1. The GitLab groups are now listed under **Source Code organizations**. Click **Test connection** to verify that the new integration is installed correctly.
1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
<img src="/docs/img/more-accounts-dropdown.png" height="350px" />
1. Click **<i class="fa-solid fa-gear"></i> Settings > Source code managers > Add > GitLab Self-Managed** and enter the personal access token generated into the **Access token** field.
1. Enter your GLSM base URL into the **URL** field.
1. Enter your GitLab group's name into the **Name of your GitLab Group** field. If your repositories are organized in subgroups, you only need to provide the name of the top-level group.
1. If you have multiple GitLab groups in your GitLab account, you need to create a source code manager per group. Repeat steps 1, 3-5 for each GitLab group.
1. The GitLab groups are now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.

</TabItem>
</Tabs>

## Next steps

- Optional: If you want to set up SSO to manage your users, see [<i class="fa-regular fa-file-lines"></i> SSO authentication](/deployment/sso).
- Optional: See [<i class="fa-regular fa-file-lines"></i> SSO authentication](/deployment/sso) to set up user management through SSO.
- You are ready to scan your org's repositories with Semgrep.
Binary file added static/img/connect-scm-list.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/more-accounts-dropdown.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.