Skip to main content
  • Semgrep in CI
  • Community Tier
  • Team & Enterprise Tier

Sample continuous integration (CI) configurations

This document provides sample configuration snippets to run Semgrep CI on various continuous integration (CI) providers.

Feature support​

Support for certain features of Semgrep App depend on your CI provider or source code management tool (SCM). The following table breaks down the features and their availability:

FeatureGitHubGitLabBitBucketCI Provider support
Diff-aware scanning✅ Yes✅ Yes✅ Yes✅ Available (may need additional set up)
Hyperlinks✅ Yes✅ Yes✅ Yes✅ Available (may need additional set up)
SCM security dashboard✅ GitHub Advanced Security Dashboard✅ GitLab SAST Dashboard❌ No❗ Only GitHub Actions and GitLab CI/CD
PR or MR comments in Semgrep App✅ Yes✅ Yes❌ No✅ CI provider agnostic; feature support is dependent on SCM

Table 1. List of features and supported SCMs and CI providers.

Diff-aware scanning
Semgrep can scan changes in files when running on a pull or merge request (PR or MR). This keeps the scan fast and reduces finding duplication.
Receiving results (findings) as PR or MR comments
This feature enables you to receive PR or MR comments from Semgrep App on the lines of code that generated a finding.
Hyperlinks to code
Semgrep App collects findings in a Findings page. In this page, you can click on a finding to view the lines of code in your repository that generated the 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:

  1. Create a semgrep.yml file in .github/workflows in the repository you want to scan.
  2. Copy the relevant code snippet provided in Sample GitHub Actions configuration file.
  3. Paste the relevant code snippet to semgrep.yml file. This is your Semgrep configuration file for GitHub Actions.
  4. Commit the configuration file under /REPOSITORY-ROOT-DIRECTORY/.github/workflows/semgrep.yml.
  5. The Semgrep job starts automatically upon detecting the committed semgrep.yml file.
note

If you are self-hosting your repository, you must use a self-hosted runner.

Sample GitHub Actions configuration file​

# Name of this GitHub Actions workflow.
name: Semgrep

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}
  # Scan mainline branches and report all findings:
  push:
    branches: ["master", "main"]
  # Schedule the CI job (this method uses cron syntax):
  schedule:
    - cron: '20 17 * * *' # Sets Semgrep to scan every day at 17:20 UTC.
    # It is recommended to change the schedule to a random time.

jobs:
  semgrep:
    # User definable name of this GitHub Actions job.
    name: Scan
    # If you are self-hosting, change the following `runs-on` value: 
    runs-on: ubuntu-latest

    container:
      # A Docker image with Semgrep installed. Do not change this.
      image: returntocorp/semgrep

    # Skip any PR created by dependabot to avoid permission issues:
    if: (github.actor != 'dependabot[bot]')

    steps:
      # Fetch project source with GitHub Actions Checkout.
      - uses: actions/checkout@v3
      # Run the "semgrep ci" command on the command line of the docker image.
      - run: semgrep ci
        env:
          # Connect to Semgrep App through your SEMGREP_APP_TOKEN.
          # Generate a token from Semgrep App > Settings
          # and add it to your GitHub secrets.
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
Alternate job that uploads findings to GitHub Advanced Security Dashboard
# Name of this GitHub Actions workflow.
name: Semgrep

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}
  # Scan mainline branches and report all findings:
  push:
    branches: ["master", "main"]
  # Schedule the CI job (this method uses cron syntax):
  schedule:
    - cron: '20 17 * * *' # Sets Semgrep to scan every day at 17:20 UTC.
    # It is recommended to change the schedule to a random time.

jobs:
  semgrep:
    # User definable name of this GitHub Actions job.
    name: Scan
    # If you are self-hosting, change the following `runs-on` value: 
    runs-on: ubuntu-latest

    container:
      # A Docker image with Semgrep installed. Do not change this.
      image: returntocorp/semgrep

    # Skip any PR created by dependabot to avoid permission issues:
    if: (github.actor != 'dependabot[bot]')

    steps:
      # Fetch project source with GitHub Actions Checkout.
      - uses: actions/checkout@v3
      # Run the "semgrep ci" command on the command line of the docker image.
      - run: semgrep ci --sarif --output=semgrep.sarif
        env:
          # Connect to Semgrep App through your SEMGREP_APP_TOKEN.
          # Generate a token from Semgrep App > Settings
          # and add it to your GitHub secrets.
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}

      - name: Upload SARIF file for GitHub Advanced Security Dashboard
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: semgrep.sarif
        if: always()

GitLab CI/CD​

To add a Semgrep configuration snippet in your GitLab CI/CD pipeline:

  1. Create or edit your .gitlab-ci.yml file in the repository you want to scan.
  2. Copy the relevant code snippet provided in Sample GitLab CI/CD configuration snippet, and then paste it to your .gitlab-ci.yml file.
  3. Commit the updated .gitlab-ci.yml file.
  4. The Semgrep job starts automatically upon detecting the committed .gitlab-ci.yml file. You can also view the job from your GitLab project's CI/CD > Pipelines page.

Sample GitLab CI/CD configuration snippet​

semgrep:
  # A Docker image with Semgrep installed.
  image: returntocorp/semgrep
  # Run the "semgrep ci" command on the command line of the docker image.
  script: semgrep ci

  rules:
  # Scan changed files in MRs, (diff-aware scanning):
  - if: $CI_MERGE_REQUEST_IID

  # Scan mainline (default) branches and report all findings.
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  variables:
    # Connect to Semgrep App through your SEMGREP_APP_TOKEN.
    # Generate a token from Semgrep App > Settings
    # and add it as a variable in your GitLab CI/CD project settings.
    SEMGREP_APP_TOKEN: $SEMGREP_APP_TOKEN

  # Other optional settings in the `variables` block:

  # Never fail the build due to findings on pushes.
  # Instead, just collect findings for semgrep.dev/manage/findings
  #   SEMGREP_AUDIT_ON: push

  # Receive inline MR comments (requires Semgrep App account)
  # Setup instructions: 
  # https://semgrep.dev/docs/semgrep-app/notifications/#enabling-gitlab-merge-request-comments
  #   GITLAB_TOKEN: $PAT
Alternate job that uploads findings to GitLab SAST Dashboard
semgrep:
  # A Docker image with Semgrep installed.
  image: returntocorp/semgrep

  rules:
  # Scan changed files in MRs, (diff-aware scanning):
  - if: $CI_MERGE_REQUEST_IID

  # Scan mainline (default) branches and report all findings.
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  variables:
    # Connect to Semgrep App through your SEMGREP_APP_TOKEN.
    # Generate a token from Semgrep App > Settings
    # and add it as a variable in your GitLab CI/CD project settings.
    SEMGREP_APP_TOKEN: $SEMGREP_APP_TOKEN

    # Upload findings to GitLab SAST Dashboard:
    SEMGREP_GITLAB_JSON: "1"

  # Other optional settings in the `variables` block:

  # Never fail the build due to findings on pushes.
  # Instead, just collect findings for semgrep.dev/manage/findings
  #   SEMGREP_AUDIT_ON: push

  # Receive inline MR comments (requires Semgrep App account)
  # Setup instructions: 
  # https://semgrep.dev/docs/semgrep-app/notifications/#enabling-gitlab-merge-request-comments
  #   GITLAB_TOKEN: $PAT

  # Run the "semgrep ci" command on the command line of the docker image and send findings
  # to GitLab SAST.
  script: semgrep ci --gitlab-sast > gl-sast-report.json || true
  artifacts:
    reports:
      sast: gl-sast-report.json

Jenkins​

note

Your UI (user interface) may vary depending on your Jenkins installation. These steps use a Classic UI Jenkins interface.

To add a Semgrep configuration snippet in your Jenkins pipeline:

  1. Create or edit your Jenkinsfile configuration file in the repository you want to scan. You can also edit your Jenkinsfile from Jenkins's interface.
  2. Copy the relevant code snippet provided in Sample Jenkins configuration snippet.
  3. Paste the code to your Jenkinsfile, and then commit the file.
  4. The Semgrep job starts automatically upon detecting the Jenkinsfile update.
  5. Optional: Create a separate CI job for diff-aware scanning, which scans only changed files in PRs or MRs, by repeating steps 1-3 and uncommenting the SEMGREP_BASELINE_REF definition provided within the code snippet.

Sample Jenkins configuration snippet​

This code snippet uses Jenkins declarative syntax.

pipeline {
  agent any
    environment {
      // The following variable is required for a Semgrep App-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 App > 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 'pip3 install semgrep'
          sh 'semgrep ci'
      }
    }
  }
}

Bitbucket Pipelines​

To add a Semgrep configuration snippet into BitBucket Pipelines:

  1. Create or edit your bitbucket-pipelines.yml file in the repository you want to scan.
  2. Copy the relevant code snippet provided in Sample BitBucket Pipelines configuration snippet, and then paste it to your bitbucket-pipelines.yml.
  3. Commit the updated bitbucket-pipelines.yml configuration file.
  4. The Semgrep job starts automatically upon detecting the committed bitbucket-pipelines.yml file. You can also view the job through BitBucket's interface, by clicking your repository > Pipelines.
  5. Optional: Create a separate CI job for diff-aware scanning, which scans only changed files in PRs or MRs, by repeating steps 1-3 and uncommenting the SEMGREP_BASELINE_REF definition provided within the code snippet.
note

These steps can also be performed through BitBucket's UI wizard. This UI wizard can be accessed through BitBucket > your repository > Pipelines > Create your first pipeline.

Sample BitBucket Pipelines configuration snippet​

image: atlassian/default-image:latest

pipelines:
  default:
    - parallel:
      - step:
          name: 'Run Semgrep scan with current branch'
          deployment: dev # https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-monitor-deployments/
          image: returntocorp/semgrep
          script:
            # The following variables are required to set up a Semgrep App-connected scan:
            - export $SEMGREP_APP_TOKEN

            # Uncomment the following line to scan changed 
            # files in PRs or MRs (diff-aware scanning): 
            # - export SEMGREP_BASELINE_REF = "origin/main"
            # - git fetch origin "+refs/heads/*:refs/remotes/origin/*"

            # Troubleshooting:

            # Uncomment the following lines if Semgrep App > Findings Page does not create links
            # to the code that generated a finding or if you are not receiving PR or MR comments.
            # - export SEMGREP_JOB_URL="${SEMGREP_REPO_URL}/addon/pipelines/home#!/results/${BITBUCKET_PIPELINE_UUID}"
            # - export SEMGREP_COMMIT=$BITBUCKET_COMMIT
            # - export SEMGREP_PR_ID=$BITBUCKET_PR_ID
            # - export SEMGREP_BRANCH=$BITBUCKET_BRANCH
            # - export SEMGREP_REPO_URL=$BITBUCKET_GIT_HTTP_ORIGIN
            # - export SEMGREP_REPO_NAME=$BITBUCKET_REPO_FULL_NAME

            - semgrep ci

Buildkite​

To add Semgrep into your Buildkite pipeline:

  1. Create or edit a pipeline.yml configuration file to add a Semgrep command as part of your pipeline. Refer to the BuildKite code snippet. This configuration file can also be stored within Buildkite.
  2. Copy the relevant code snippet provided in Sample Buildkite configuration snippet.
  3. If you are using Buildkite to store the configuration, save the updated file. Otherwise, commit the updated configuration file into the /.buildkite folder within the target repository.
  4. The Semgrep job starts automatically upon detecting the committed pipeline.yml file. You can also view the job through BitBucket's interface, by clicking your repository > Pipelines.
  5. Optional: Create a separate CI job for diff-aware scanning, which scans only changed files in PRs or MRs, by repeating steps 1-3 and uncommenting the SEMGREP_BASELINE_REF definition provided within the code snippet.
note

These steps can be performed from within Buildkite's interface. From Buildkite's main page, click Pipelines > ➕ button to perform these steps within Buildkite's UI.

Sample Buildkite configuration snippet​

- label: ":semgrep: Semgrep"
  commands:

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

    # Uncomment the following lines if Semgrep App > Findings Page does not create links
    # to the code that generated a finding or if you are not receiving PR or MR comments.
    # - export SEMGREP_COMMIT=${BUILDKITE_COMMIT}
    # - export SEMGREP_PR_ID=${BUILDKITE_PULL_REQUEST}
    # - export SEMGREP_BRANCH=${BUILDKITE_BRANCH}
    # - export SEMGREP_REPO_URL="$(echo "$BUILDKITE_REPO" | sed -e 's#.\{4\}$##')"
    # - echo "$BUILDKITE_REPO" | sed 's#https://github.com/##' | sed 's#.git##'
    # - export SEMGREP_REPO_NAME="$(echo "$BUILDKITE_REPO" | sed -e 's#https://github.com/##' | sed -e 's#.git##')"
    
    - semgrep ci 
  
  plugins:
    - docker#v3.7.0:
        image: returntocorp/semgrep
        environment:
          # The following variable is required for a Semgrep App-connected scan:
          - "SEMGREP_APP_TOKEN"

CircleCI​

To add Semgrep into your CircleCI pipeline:

  1. Create or edit your config.yml configuration file in the repository you want to scan.
  2. Copy the relevant code snippet provided in Sample CircleCI configuration snippet.
  3. Commit the updated config.yml configuration file into the /.circleci folder in the target repository.
  4. The Semgrep job starts automatically upon detecting the config.yml update.
  5. Optional: Create a separate CI job for diff-aware scanning, which scans only changed files in PRs or MRs, by repeating steps 1-3 and uncommenting the SEMGREP_BASELINE_REF definition provided in the code snippet.

Sample CircleCI configuration snippet​

version: 2.1
jobs:
  semgrep-scan:
    parameters:
      default_branch:
        type: string
        default: main
    environment:
      # Uncomment the following line to scan changed 
      # files in PRs or MRs (diff-aware scanning): 
      # - export SEMGREP_BASELINE_REF = "origin/main"
      # - git fetch origin "+refs/heads/*:refs/remotes/origin/*"
      # SEMGREP_BASELINE_REF: << parameters.default_branch >>

      # Troubleshooting:

      # Uncomment the following lines if Semgrep App > Findings Page does not create links
      # to the code that generated a finding or if you are not receiving PR or MR comments.
      # SEMGREP_REPO_NAME: '$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME'
      # SEMGREP_REPO_URL: << pipeline.project.git_url >>
      # SEMGREP_BRANCH: << pipeline.git.branch >>

    docker:
      - image: returntocorp/semgrep
    steps:
      - checkout

      # Uncomment the following lines if Semgrep App > Findings Page does not create links
      # to the code that generated a finding or if you are not receiving PR or MR comments.
      # - run:
      #     name: "Manually set environment variables"
      #     command: |
      #         echo 'export SEMGREP_COMMIT=$CIRCLE_SHA1' >> $BASH_ENV
      #         echo 'export SEMGREP_PR_ID=${CIRCLE_PULL_REQUEST##*/}' >> $BASH_ENV
      #         echo 'export SEMGREP_JOB_URL=$CIRCLE_BUILD_URL' >> $BASH_ENV
      - run:
          name: "Semgrep scan"
          command: semgrep ci
workflows:
  main:
    jobs:
      - semgrep-scan

Azure Pipelines​

To add Semgrep into Azure Pipelines:

  1. Access the YAML pipeline editor within Azure Pipelines by following the YAML pipeline editor guide.
  2. Copy the relevant code snippet provided in Sample Azure Pipelines configuration snippet into the Azure Pipelines YAML editor.
  3. Save the code snippet.
  4. Set environment variables.
  5. Group the environment variables as a variable group.
  6. Optional: Create a separate CI job for diff-aware scanning, which scans only changed files in PRs or MRs, by repeating steps 1-4 and and adding SEMGREP_BASELINE_REF as an environment variable.

Sample Azure Pipelines configuration snippet​

# trigger:
#  - master

pool:
  vmImage: ubuntu-latest
variables:
- group: Semgrep app token group

steps: 

- script: |
    python -m pip install --upgrade pip
    pip install semgrep
    semgrep ci
  env: 
    SEMGREP_PR_ID: $(System.PullRequest.PullRequestNumber)

Setting environment variables in Azure Pipelines​

Set these variables within Azure Pipelines UI following the steps in Environment variables:

  • SEMGREP_APP_TOKEN

Set these environment variables to troubleshoot the links to the code that generated a finding or if you are not receiving PR or MR comments:

  • SEMGREP_JOB_URL
  • SEMGREP_COMMIT
  • SEMGREP_BRANCH
  • SEMGREP_REPO_URL
  • SEMGREP_REPO_NAME

Set this environment variable for diff-aware scanning:

  • SEMGREP_BASELINE_REF. Its value is typically your trunkline branch, such as main or master.

Other providers​

To run Semgrep CI on any other provider, use the returntocorp/semgrep image, and run the semgrep ci command with SEMGREP_BASELINE_REF set for diff-aware scanning.

Note: If you need to use a different image than docker, install Semgrep CI by pip install semgrep.

Using the configuration reference, you can run Semgrep in the following CI providers:

  • AppVeyor
  • Bamboo
  • Bitrise
  • Buildbot
  • Codeship
  • Codefresh
  • Drone CI
  • TeamCity CI
  • Travis CI

Is your CI provider missing? Let us know by filing an issue.

Find what you needed in this doc? Join the Semgrep Community Slack group to ask the maintainers and the community if you need help.