> ## Documentation Index
> Fetch the complete documentation index at: https://semgrep-ee9d73d8-mintlify-b75b9a88.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Add a GitLab repository to Semgrep Managed Scans
> Add GitLab repositories to your Semgrep organization in bulk without adding or changing your existing CI workflows through **Managed Scans**.
## Prerequisites and permissions
Semgrep Managed Scans requires one of the following plans:
* GitLab Premium
* GitLab Ultimate
* GitLab Self Managed
You must provide a GitLab group access token or personal access token to Semgrep. The token must have the `api` scope assigned to it.
When onboarding to Semgrep Managed Scans, the group or user assigned to the token must have the **`Owner`** or **`Admin`** role. The `Owner` or `Admin` role is required because Managed Scans of GitLab repositories require group webhooks. Semgrep uses these webhooks to facilitate diff-aware scans and create pull request (PR) comments.
Webhooks are enabled by default when you set up Managed Scans and add GitLab as a source code manager. After onboarding is complete, you can downgrade the token’s role to `Developer`.
See [SCM permissions](/deployment/prepare/scm-permissions#permissions) for more information about the permissions used by Semgrep.
## Enable Semgrep Managed Scans and scan your first repository
In Semgrep AppSec Platform, click **Projects**.
Click **Scan new project > Semgrep Managed Scan**.
In the **Enable Managed Scans for repos** page, select the repositories you want to add to Semgrep Managed Scans.
i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided.
Click **+ Connect more**.
Select **GitLab**.
In the **Set up Managed Scans** page that appears, provide the information needed by Semgrep to connect to your GitLab project:
i. Select **GitLab Cloud** or **GitLab Self-Managed**.
ii. Provide your **Access token**.
iii. Provide your **GitLab group**.
iv. *For GitLab Self-Managed users only*: provide the **GitLab URL**.
v. Click **Connect**.
Repeat the steps above for each additional GitLab group you'd like added to Semgrep.
You have finished setting up a Semgrep managed scan.
* After enabling Managed Scans, Semgrep performs a full scan in batches on all the repositories.
* Once a repository has been added to Semgrep AppSec Platform, it becomes a **project**. A project in Semgrep AppSec Platform includes all the findings, history, and scan metadata of that repository.
* Projects with a Managed Scan configuration are tagged with `managed-scan`, regardless of whether the project is actively being scanned by Semgrep Managed Scans or not. The **Projects** list also contains pending scans and scans that never started.
## Add additional GitLab projects
You can enable Semgrep Managed Scans for additional repositories after onboarding using the following steps:
In Semgrep AppSec Platform, click **Projects**.
Click **Scan new project > Semgrep Managed Scan**.
In the **Enable Managed Scans for repos** page, select the repositories you want to add to Semgrep Managed Scans.
i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided.
Select the repositories you want to scan from the list.
Click **Enable Managed Scans**. The **Enable Managed Scans** dialog appears. By default, Semgrep runs both full and diff-aware scans.
Optional: Disable PR or MR diff-aware scans by turning off the **Enable PR/MR scans** toggle.
Click **Enable**.
### If the page doesn't display any repositories
Ensure that you've connected your GitLab account by following the steps in [Connect a source code manager](/deployment/connect-scm) and confirm the [PAT is created with the required `API` scope](https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes) by someone assigned the [role of **Maintainer** or **Owner**](https://docs.gitlab.com/ee/user/permissions.html#roles).
i. Once you successfully create the connection, the role for the person who owns the token can be downgraded to **Developer**.
In Semgrep AppSec Platform, click **Projects**.
If the page doesn't display the repository you want to add, click **Can't find your project? > Sync projects**.
If the page doesn't display any repositories, click **Sync projects**.
Optional: Perform a hard refresh (Ctrl+F5 or Cmd+Shift+R).
### Convert or migrate an existing Semgrep CI job
You can immediately add any existing project to Managed Scans.
Follow the steps in [Enable Semgrep Managed Scans](#enable-managed-scanning-and-scan-your-first-repository).
Delete the `.gitlab-ci.yml` file in your GitLab repository if appropriate.
If you plan to continue running some scans in GitLab CI/CD Pipelines (for example, using Managed Scans to run weekly full scans but GitLab CI/CD Pipelines for diff-aware scans) you can leave the workflow file in place, and edit it to reflect your desired configuration.
**TIP**
Semgrep preserves your findings, scans, and triage history.
## Scan management and configuration
### Manually run a full scan
In Semgrep AppSec Platform, click **Projects**.
Search for your repository's name.
Click the **gear icon** to access the settings page for that repository.
Click **Run a new scan > Rule-based detection**.
> You can manually run a full scan for both primary and non-primary branches.
### Re-run a failed scan or a scan that never finished
In Semgrep AppSec Platform, click **Projects**.
Click on the project name.
Find the scan that failed or never finished using the **Status** column, and click **Details** to open the **Scan logs** dialog.
Ensure that you're on the **Overview** tab of the **Scan logs** dialog, then click **Retry scan**.
### Disable diff-aware scans on PRs
In Semgrep AppSec Platform, click **Projects**.
Search for your repository's name.
Click the **window icon** under **Details** to access the settings page for that repository.
Click the toggle for diff-aware scans.
### Delete a project
In Semgrep AppSec Platform, click **Projects**.
Search for your repository's name.
Click the **window icon** under **Details** to access the settings page for that repository.
Click the dropdown at the header and click **Delete project**.
To delete an archived project:
In Semgrep AppSec Platform, click **Projects**.
Switch to the **Not Scanning** tab of the **Projects** page.
Select the checkbox to **Show archived** projects.
Search for the archived repository's name.
Click the **window icon** under **Details** to access the settings page for that repository.
Click the dropdown at the header and click **Delete project**.
### Configure fail open to prevent diff-aware scans from blocking pull requests and merge requests
By default, diff-aware managed scans are set to **fail open** if a scan errors out or takes too long. This means that diff-aware scans are marked as successful on the pull request (PR) or merge request (MR), even if they haven't completed after the specified timeout, allowing you to make the Semgrep status check required in your source code manager (SCM) while not blocking someone from merging a PR or MR if the check encounters an unexpected issue or takes too long.
#### How fail open works
If enabled, the fail open feature is triggered whenever you open a PR or MR.
Initially, Semgrep sends an update to mark the PR or MR as `pending`.
Once the diff-aware scan begins, the PR or MR is updated to a status of `running`.
The diff-aware scan completes, and the PR or MR is updated to a status of `succeeded` or `failed`.
If the diff-aware scan is in `pending` or `running` status longer than the configured timeout, then the fail open process updates the PR or MR to display a status of `succeeded`. This prevents the Semgrep scan from blocking the developer from merging their changes.
If Semgrep marks a PR or MR as `succeeded`, you can merge the PR or MR without waiting for the diff-aware scan to complete. However, if the PR or MR is still open and the scan completes *after* the fail open timeout is reached, Semgrep can still report the findings and mark the status as `failed`.
#### Configure fail open
By default, fail open is enabled. However, you can disable this feature and adjust the timeout value:
Sign in to [Semgrep AppSec Platform](https://semgrep.dev/login).
Go to **Settings > General > Managed Scans**.
Click the **Fail open** toggle to turn off this feature.
Set the **Timeout** value in minutes. The default value is **10 minutes**, the minimum value is **1 minute**, and the maximum value is **60 minutes**.
## Disable webhooks
Semgrep Managed Scans of GitLab projects require webhooks. The webhooks are enabled by default when you add GitLab as a source code manager when setting up Managed Scans. You can disable webhooks at any time by following these steps:
In Semgrep AppSec Platform, go to [Settings > Source code managers](https://semgrep.dev/orgs/-/settings/source-code).
Find your GitLab connection, and click the toggle to disable **Incoming webhooks**.
## Revoke Semgrep's access to your repositories
The following steps revoke the code access you previously granted Semgrep for all repositories you selected.
In Semgrep AppSec Platform, click **Settings > Source Code Managers**.
On the entry of the SCM you want to remove, click **Remove app**.
Click **Remove** to confirm.
## Turn off Managed Scans for specific repositories in Semgrep AppSec Platform
Sign in to Semgrep AppSec Platform.
Go to Projects and find the project you no longer want scanned with Semgrep Managed Scans. Click the project's **Details** page > **Settings** tab.
Toggle the switch for **Managed diff scans** to turn off scans of new pull requests and merge requests and **Managed full scans** to turn off full scans of the base branch.
## Appendices
### Scan logs
To view your scan logs in Semgrep AppSec Platform, go to **Projects**, then click on the project name. The projects in the list are sorted by scan date, with the most recent scans listed first.
**INFO**
It can take a few minutes for your latest scan logs to appear. However, if the logs do not update 15 minutes after the scan, there may be issues with the scan itself.
### Scan statistics
**Scan statistics**, such as how many of your repositories are being scanned, the scan success rate, and so on, can be provided once a week upon request. Contact your Semgrep account manager to request scan statistics.