Documentation Index
Fetch the complete documentation index at: https://docs.semgrep.dev/llms.txt
Use this file to discover all available pages before exploring further.
Feature support
Support for certain features of Semgrep AppSec Platform depends on your CI provider or source code management (SCM) tool.| Feature | GitHub with GitHub Actions | GitLab with GL CI/CD | *GitHub, GitLab, or Bitbucket with other CI providers |
|---|---|---|---|
| Diff-aware scanning | ✅ | ✅ | ✅ |
| Hyperlinks | ✅ | ✅ | ✅ |
| PR or MR comments | ✅ | ✅ | ✅ |
| SCM security dashboard | ✅ GitHub Advanced Security Dashboard | ✅ GitLab Security Dashboard | ❌ No |
Feature definitions
| Feature | Description |
|---|---|
| Diff-aware scanning | Semgrep AppSec Platform can scan only changes in files when running on a pull request or merge request (PR or MR). This keeps the scan fast and reduces finding duplication. |
| Hyperlinks to code | Semgrep AppSec Platform collects findings in a Findings page. In this page, you can click on a finding to return to your SCM (GitHub, GitLab, or Bitbucket) to view the lines of code in your repository that generated the finding. |
| Receiving results (findings) as PR or MR comments | This feature enables you to receive PR or MR comments from Semgrep AppSec Platform on the lines of code that generated a finding. |
| SCM security dashboard | Send Semgrep findings to your SCM’s security dashboard. |
GitHub Actions
To add a Semgrep configuration file in your GitHub Actions pipeline:Copy the relevant code snippet provided in Sample GitHub Actions configuration file.
Paste the relevant code snippet to
semgrep.yml file. This is your Semgrep configuration file for GitHub Actions.The Semgrep job starts automatically upon detecting the committed
semgrep.yml file.NOTEIf you are self-hosting your repository, you must use a self-hosted runner.
Sample GitHub Actions configuration file
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.GitLab CI/CD
To add a Semgrep configuration snippet in your GitLab CI/CD pipeline:Copy the relevant code snippet provided in Sample GitLab CI/CD configuration snippet, and then paste it to your
.gitlab-ci.yml file.Sample GitLab CI/CD configuration snippet
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.Prefer to use GitLab group variables? See this guide for an appropriate configuration.Jenkins
NOTEYour user interface (UI) may vary depending on your Jenkins installation. The following steps refer to Jenkins’ Classic UI.
Create or edit your
Jenkinsfile configuration file in the repository you want to scan. You can also edit your Jenkinsfile from Jenkins’s interface.Copy the relevant code snippet provided in Sample Jenkins configuration snippet.
Sample Jenkins configuration snippet
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.Bitbucket Pipelines
To add a Semgrep configuration snippet into Bitbucket Pipelines:Copy the relevant code snippet provided in Sample Bitbucket Pipelines configuration snippet, and then paste it to your
bitbucket-pipelines.yml.The Semgrep job starts automatically upon detecting the committed
bitbucket-pipelines.yml file. You can view the job through Bitbucket’s interface, by clicking REPOSITORY_NAME > Pipelines.Optional: Create a daily scheduled run for the custom pipeline on the main branch by scheduling a pipeline in Bitbucket.
NOTEThese steps can also be performed through Bitbucket’s UI wizard. This UI wizard can be accessed through Bitbucket > REPOSITORY_NAME > Pipelines > Create your first pipeline.
Sample Bitbucket Pipelines configuration snippet
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.Buildkite
To add Semgrep into your Buildkite pipeline:Prepare a configuration file to add a Semgrep scan as part of your pipeline. This configuration file can be stored within Buildkite or as a
pipeline.yml file in the target repository.Copy the code snippet provided in Sample Buildkite configuration snippet, making alterations if necessary for your environment.
If you are using Buildkite to store the configuration, save the updated file. Otherwise, commit the updated
pipeline.yml file into the /.buildkite folder within the target repository.The Semgrep job starts automatically upon detecting the committed
pipeline.yml file. Alternatively, if you are using the Buildkite UI, you can select New build. You can view the job through Buildkite’s interface by clicking Pipelines > pipeline name.NOTEThese steps can be performed within Buildkite’s UI. To do so, navigate to Buildkite’s main page, and click Pipelines > New Pipeline.
Sample Buildkite configuration snippet
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans according to the products you have enabled in Semgrep AppSec Platform. The provided environment variables are commonly needed to correctly configure scans from Buildkite.This file configures two mutually exclusive command steps, one for full scans, and one for diff-aware scans. The latter is used for pull requests or merge requests.In order for this configuration to run the correct type of scan for each condition, it requires both branch filtering and configuration to build on pull requests.You can run specific product scans by passing the appropriate argument, such as
Branch filtering
In the Buildkite UI, go to the pipeline Settings and select the connected source code manager in the left sidebar.
Under Branch Limiting, enter your default branch name in the Branch Filter Pattern box. You can include any other branch names that require full scans as well, such as
release-*.Build on pull requests
To run diff-aware scans, your pipeline must run builds on pull requests or merge requests. Buildkite integrates with several source code managers and each one has different options to handle PRs or MRs. The most common options are a checkbox within the pipeline settings, or webhooks within the source control manager. Review the documentation for your source control system to ensure your Semgrep pipeline builds on pull requests or merge requests.--supply-chain.CircleCI
To add Semgrep into your CircleCI pipeline:Create a context:i. In CircleCI web app, click Organization Settings > Contexts.ii. Click Create Context.iii. Enter
semgrep as the name for the context.iv. Click Add Environment Variable and enter your SEMGREP_APP_TOKEN.Copy the relevant code snippet provided in Sample CircleCI configuration snippet.
If your default branch is not
main, change the occurrences of main to the name of your default branch.Commit the updated
config.yml configuration file into the /.circleci folder in the target repository.Sample CircleCI configuration snippet
- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.Azure Pipelines
INFOScanning a project with the
semgrep ci command requires the project to be version-controlled by Git. If you have Azure Repos that are version-controlled with Team Foundations Version Control, they must be migrated to Git to be scanned with semgrep ci and have results reported to the Semgrep AppSec Platform.Access the YAML pipeline editor within Azure Pipelines by following the YAML pipeline editor guide.
Copy the code snippet provided in Sample Azure Pipelines configuration snippet into the Azure Pipelines YAML editor.
Sample Azure Pipelines configuration snippet
This configuration snippet is tested with hosted Azure runners. If you are using self-hosted runners, you may need to make adjustments to ensure that the necessary software is available. Consult Semgrep with self-hosted Ubuntu runners in Azure Pipelines for two recommended options.- Default
- Semgrep CE
The following configuration creates a CI job that runs scans using the products and options you have enabled in Semgrep AppSec Platform.You can run specific product scans by passing an argument, such as
--supply-chain. View the list of arguments.Set environment variables in Azure Pipelines
Semgrep minimally requires the variableSEMGREP_APP_TOKEN in order to report results to the platform, and other variables may be helpful as well. To set these variables in Azure Pipelines:Set up a variable group called
Semgrep_Variables.Set
SEMGREP_APP_TOKEN in the variable group, following the steps for secret variables. The variable is mapped into the env in the provided config.Optional: Add the following environment variables to the group if you aren’t seeing hyperlinks to the code that generated a finding, or if you are not receiving PR or MR comments. Review the use of these variables at Environment variables for creating hyperlinks in Semgrep AppSec Platform.These variables are not sensitive and do not need to be secret variables.
SEMGREP_REPO_NAMESEMGREP_REPO_URLSEMGREP_BRANCHSEMGREP_COMMITSEMGREP_JOB_URL
Set variables for diff-aware scanning. The provided config sets
SEMGREP_PR_ID to the system variable System.PullRequest.PullRequestId and SEMGREP_BASELINE_REF to origin/master within the script section of the config. The value of SEMGREP_BASELINE_REF is typically your trunk or default branch, so if you use a different branch than master, update the name accordingly. as main or master.- If you prefer not to implement diff-aware scanning, you can skip setting these variables and remove the
elifsection of thescriptstep.
For diff-aware scans: add a build validation policy. Adding and enabling a branch policy for build validation is required to trigger Azure Pipelines on pull requests.
Other providers
To run Semgrep CI on any other provider, use thesemgrep/semgrep image, and run the semgrep ci command with SEMGREP_BASELINE_REF set for diff-aware scanning.
By setting various CI environment variables, you can run Semgrep in the following CI providers:
- AppVeyor
- Bamboo
- Bitrise
- Buildbot
- Codeship
- Codefresh
- Drone CI
- Semaphore
- TeamCity CI
- Travis CI