Add Semgrep manually to CI providers

YOUR DEPLOYMENT JOURNEY

You have gained the necessary resource access and permissions required for deployment.
You have created a Semgrep account and organization.
For GitHub and GitLab users: You have connected your source code manager.
Optionally, you have set up SSO.

This guide documents the steps required to create a Semgrep job for CI providers for which Semgrep AppSec Platform offers no explicit guidance. See Add Semgrep to CI before proceeding to ensure that this guide applies to your CI provider. Skip this guide if you have already configured a CI job. The steps provided here are known to work with the following CI providers:

AppVeyor
Bamboo
Bitrise
Buildbot
Codeship
Codefresh
Drone CI
Nomad
Semaphore
TeamCity CI
Travis CI

General steps

The following steps provide an overview of the process. View the succeeding sections for detailed instructions.

Create a token called SEMGREP_APP_TOKEN.

Add this token as a credential, secret, or token to your CI provider.

Create a CI job that runs Semgrep. This step is typically achieved by committing a CI configuration file. The syntax of the configuration file depends on your CI provider.

The CI job can automatically start to run depending on your configuration. If the job does not start, run the job through the CI provider’s interface or by committing code.

Semgrep detects the SEMGREP_APP_TOKEN, sends it to Semgrep AppSec Platform for verification, and if verified, sends findings to Semgrep AppSec Platform.

Define additional environment variables to enable other Semgrep AppSec Platform features. This is done last because it is easier to troubleshoot modifications to jobs after ensuring that the base CI job runs correctly.

The next sections go over these steps in detail.

Create a SEMGREP_APP_TOKEN

To create a SEMGREP_APP_TOKEN, follow these steps:

Click Settings > Tokens.

Click Create new token.

Copy the name and value, then click Save.

Store the token value into your CI provider. Tokens can also be referred to as secrets, credentials, or secure variables. The steps to do this vary depending on your CI provider.

Create a Semgrep CI job

Add Semgrep to your CI pipeline. Do either of the following:

i. Reference or add the Semgrep Docker image. This is the recommended method.

ii. Add pipx install semgrep (or uv tool install semgrep if you use uv) into your configuration file as a step or command, depending on your CI provider’s syntax. See the Python Packaging guide for more on installing standalone Python CLI tools.

Add semgrep ci as a step or command.

Set the SEMGREP_APP_TOKEN environment variable within your configuration file.

The following example is a Jenkinsfile that adds Semgrep through the Docker image:

Add Semgrep through the Docker image.

pipeline {
  agent any
    environment {
      // The following variable is required for a Semgrep AppSec Platform-connected scan:
      SEMGREP_APP_TOKEN = credentials('SEMGREP_APP_TOKEN')

      // Uncomment the following line to scan changed
      // files in PRs or MRs (diff-aware scanning):
      // SEMGREP_BASELINE_REF = "main"

      // Troubleshooting:

      // Uncomment the following lines if Semgrep AppSec Platform > Findings Page does not create links
      // to the code that generated a finding or if you are not receiving PR or MR comments.
      // SEMGREP_JOB_URL = "${BUILD_URL}"
      // SEMGREP_COMMIT = "${GIT_COMMIT}"
      // SEMGREP_BRANCH = "${GIT_BRANCH}"
      // SEMGREP_REPO_NAME = env.GIT_URL.replaceFirst(/^https:\/\/github.com\/(.*).git$/, '$1')
      // SEMGREP_REPO_URL = env.GIT_URL.replaceFirst(/^(.*).git$/,'$1')
      // SEMGREP_PR_ID = "${env.CHANGE_ID}"
    }
    stages {
      stage('Semgrep-Scan') {
        steps {
            sh '''docker pull semgrep/semgrep && \
            docker run \
            -e SEMGREP_APP_TOKEN=$SEMGREP_APP_TOKEN \
            -e SEMGREP_REPO_URL=$SEMGREP_REPO_URL \
            -e SEMGREP_REPO_NAME=$SEMGREP_REPO_NAME \
            -e SEMGREP_BRANCH=$SEMGREP_BRANCH \
            -e SEMGREP_COMMIT=$SEMGREP_COMMIT \
            -e SEMGREP_PR_ID=$SEMGREP_PR_ID \
            -v "$(pwd):$(pwd)" --workdir $(pwd) \
            semgrep/semgrep semgrep ci '''
      }
    }
  }
}

The next example is a Jenkins configuration file that installs Semgrep:

Add Semgrep by installing it.

pipeline {
  agent any
  environment {
    // You need to set the token as an environment variable
    // (see Create a `SEMGREP_APP_TOKEN` section).
    SEMGREP_APP_TOKEN = credentials('SEMGREP_APP_TOKEN')
  }
  stages {
    stage('Semgrep-Scan') {
      steps {
        // Install and run Semgrep:
        sh 'pipx install semgrep'
        sh 'semgrep ci'
      }
    }
  }
}

Run the job

Depending on your CI provider and configuration, the job runs automatically. Otherwise, trigger the job by committing code or opening a PR or MR.

Verify the connection

To verify that your Semgrep CI job is connected to Semgrep AppSec Platform:

Go to your Semgrep AppSec Platform Projects page.

Verify that your repository is listed on the Projects page and that Semgrep AppSec Platform is running a scan.

Troubleshoot your CI job

Semgrep attempts to automatically detect certain CI values, such as your repository’s name and URL. These values are used to provide context to findings in Semgrep AppSec Platform and hyperlinks to the code that generated the finding. Refer to the following table for common issues and the corresponding environment variables you can set to fix them:

Issue	Environment variable to set	Affected CI providers
Can’t establish a connection to Semgrep AppSec Platform.	`SEMGREP_APP_TOKEN`	Must be set for all CI providers.
Semgrep doesn’t scan your PRs or MRs.	`SEMGREP_BASELINE_REF`	Required for CI providers except GitHub Actions or GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_REPO_NAME`	Set these environment variables as needed to troubleshoot broken links for any CI provider except GitHub Actions and GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_REPO_URL`	Set these environment variables as needed to troubleshoot broken links for any CI provider except GitHub Actions and GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_BRANCH`	Set these environment variables as needed to troubleshoot broken links for any CI provider except GitHub Actions and GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_JOB_URL`	Set these environment variables as needed to troubleshoot broken links for any CI provider except GitHub Actions and GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_COMMIT`	Set these environment variables as needed to troubleshoot broken links for any CI provider except GitHub Actions and GitLab CI/CD.
Can’t click hyperlinks to your repository from Semgrep AppSec Platform, nor can Semgrep AppSec Platform create PR or MR comments.	`SEMGREP_PR_ID`	Required to enable hyperlinks for Azure Pipelines.

Data collected by Semgrep AppSec Platform

When running in CI, Semgrep runs fully in the CI build environment. Unless you have explicitly granted code access to Semgrep, your code is not sent anywhere.

Semgrep AppSec Platform collects findings, which includes the line number of the code match, but not the code. It is hashed using a one-way hashing function.
Findings data is used to generate line-specific hyperlinks to your source code management system and support other Semgrep functions.

Next steps

You’ve set up Semgrep to scan in your repository and send findings after each scan. Your core deployment is almost complete. Remaining steps include:

Optional: Customize your CI job.
For software composition analysis (SCA) scans using Jenkins or Maven: Set up SCA scans for your infrastructure.
Set up diff-aware scanning for feature branches (non-trunk branches) when a pull request or merge request is open. This is a prerequisite to receiving PR or MR comments. See Set up diff-aware scans.
Set up PR or MR comments, which post findings to developers in your SCM. This involves developers in the security process as active participants. See PR or MR comments for next steps.

Documentation Index

​General steps

​Create a SEMGREP_APP_TOKEN

​Create a Semgrep CI job

​Run the job

​Verify the connection

​Troubleshoot your CI job

​Data collected by Semgrep AppSec Platform

​Next steps