How to trigger diff-aware scans

When working with a CI provider, you can set Semgrep to run diff-aware scans as well as full scans. Diff-aware scans run on your code before and after some baseline, and only report findings newly introduced in the commits after that baseline.

Azure DevOps

To add this configuration in Azure Pipelines, follow the general instructions provided in Sample CI configurations: Azure Pipelines. If your repository’s default branch is not main, change the references to main to the name of your default branch.

steps:
- checkout: self
  clean: true
  fetchDepth: 20
persistCredentials: true
- script: |
    python -m pip install --upgrade pipx
    pipx install semgrep
    if [ $(System.PullRequest.PullRequestId) -ge 0 ]; then
      echo "Pull Request Scan from branch: $(Build.SourceBranchName)"
      git fetch origin main:origin/main
      export SEMGREP_PR_ID=$(System.PullRequest.PullRequestId)
      export SEMGREP_BASELINE_REF='origin/main'
      semgrep ci

If you are running both full and diff-aware scans for the repository, you can use if clauses or define separate templates for full scans and diff-aware scans in Azure Pipelines. Diff-aware scans require the use of the SEMGREP_PR_ID and SEMGREP_BASELINE_REF variables, while full scans do not. Full scans are typically run on the condition if [ $(Build.SourceBranchName) = "main" ].

Bitbucket

In the Bitbucket Pipelines configuration file, set SEMGREP_BASELINE_REF to enable diff-aware scanning:

image: semgrep/semgrep:latest

pipelines:
  ...
  pull-requests:
    '**':
      - step:
        name: Semgrep scan on PR
        script:
          - export SEMGREP_APP_TOKEN=$SEMGREP_APP_TOKEN
          - export BITBUCKET_TOKEN=$PAT # Necessary for PR comments
          # Change to your default branch if different from main
          - export SEMGREP_BASELINE_REF="origin/main"
          - git fetch origin "+refs/heads/*:refs/remotes/origin/*"
          - semgrep ci

Github

Include the following definition in your GitHub Actions configuration file to enable diff-aware scanning:

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}

Example

# Name of this GitHub Actions workflow.
name: Semgrep

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}

jobs:
  semgrep:
    # User definable name of this GitHub Actions job.
    name: semgrep/ci
    # 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: semgrep/semgrep

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

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

Gitlab

Set up your .gitlab-ci.yml conditions (usually rules) to run a scan if $CI_MERGE_REQUEST_IID is defined. Semgrep automatically runs a diff-aware scan if the variable is present, as it is in merge request pipelines:

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

Example

semgrep:
  # A Docker image with Semgrep installed.
  image: semgrep/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

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

Jenkins

Jenkins is highly configurable and there are multiple approaches to setting up diff-aware scans.

See the following articles for detailed guides:

Set up Jenkins pipeline projects for Bitbucket repositories

Full and diff-aware scans with GitHub and Jenkins

Other CI providers

Set SEMGREP_BASELINE_REF to enable diff-aware scanning:

export SEMGREP_BASELINE_REF="main"

You may need to perform additional git checkout steps to ensure that the configured baseline ref is available in the scan environment along with the source branch.