Configure blocking findings and errors

This article documents how Semgrep pipelines handle blocking findings and errors in its default setup. This article also provides three configuration options you can use to change or revert to the default behavior.

Default configuration of blocking findings and error suppression

Semgrep can be used to block pull requests (PRs) or merge requests (MRs) when it matches a blocking finding. When one or more findings is blocking, Semgrep returns exit code 1, and you can use this result to set up additional checks to enforce a block in your CI/CD pipeline, such as not allowing merge of the PR/MR. This action applies to both full scans and diff-aware scans.

Blocking findings can be defined as:

• Findings defined in the Policies page of Semgrep AppSec Platform. Avoid blocking findings by removing rules from the Block rule mode of the Policies page.
• If you do not use Semgrep AppSec Platform with Semgrep in CI (that is, you are using a stand-alone setup), blocking findings encompass all Semgrep findings. Any finding in this setup blocks your PRs or MRs.

By default, Semgrep does not block your pipeline when it encounters an internal error. In case of an internal error, Semgrep sends an anonymous crash report to a crash-reporting server and does not block your CI pipeline. To change the default configuration, see the sections below.

tip

The process to enforce a block on a PR or MR after Semgrep exits with error code 1 is dependent on your CI provider. Review your CI provider's documentation for further information.

Configuration options for blocking findings and errors

Configure, change or revert to the default setup of blocking findings and errors in your CI pipeline using the following options in CI configuration file:

CI option	Description
semgrep ci or semgrep ci --suppress-errors	Default: CI fails on blocking findings, CI passes on internal errors.
semgrep ci --no-suppress-errors	CI fails on blocking findings, CI fails on internal errors.
semgrep ci || true	CI passes on blocking findings, CI passes on internal errors.

To change this configuration, insert one of the configuration options (flags) after the following keys in CI YAML configuration file of Semgrep:

• On GitHub, insert the flag after the run key (for example, run: semgrep ci --suppress-errors to state the default option).
• On GitLab, insert the flag after the script key (for example, script: semgrep ci --suppress-errors to state the default option).
• Insert these flags in an equivalent key in configuration files of other CI providers.

See the Examples of blocking findings and errors configuration below.

info

• For more information about specific Semgrep exit codes, see CLI reference.

To find more details about some of these configuration options, see the following list:

• semgrep ci - The default state. Semgrep in CI fails on blocking findings, CI passes on internal errors. If Semgrep encounters an internal error, it sends an anonymous crash report to a crash-reporting server and exits with exit code 0 (success). Consequently, Semgrep in CI does not report other statuses than 0 or 1 by default (success or a blocking finding). Optional: Define this setting explicitly using the --suppress-errors flag.
• semgrep ci --no-suppress-errors - Semgrep in CI fails on blocking findings, CI fails on internal errors. If you use this flag, all exit codes, including internal errors, surface to the CI provider.
• semgrep ci || true - Semgrep in CI passes on blocking findings, CI passes on internal errors.

Examples of blocking findings and errors configuration

The following code displays Semgrep in the CI configuration file for GitHub Actions (GHA) with the default setup (run: semgrep ci):

# Name of this GitHub Actions workflow.
name: Semgrep

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}
  # Scan on-demand through GitHub Actions interface:
  workflow_dispatch: {}
  # 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: 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@v4
      # 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 }}

The default configuration displayed above lets Semgrep in CI fail on blocking findings but pass on internal errors. If Semgrep encounters an internal error, it sends an anonymous crash report to a crash-reporting server and exits with exit code 0. Consequently, Semgrep in CI does not report other statuses than 0 or 1 by default (0 reports success, 1 reports blocking findings).

Optional: Define this configuration explicitly using the --suppress-errors flag. The resulting code is the following:

steps:
  - uses: actions/checkout@v4
  - name: Scan and suppress internal errors
    run: semgrep ci --suppress-errors

To change the configuration of blocking findings and errors in GitLab, insert one of the configuration options after the script key. For example, use script: semgrep ci --suppress-errors to state the default option. Similarly, use options described above, such as script: semgrep ci --no-suppress-errors or script: semgrep ci || true.

The following shortened code snippets in multiple tabs display the position of the default flag in configuration files of various CI providers:

GitHub Actions

steps:
- uses: actions/checkout@v4
- name: Scan and suppress internal errors
   run: semgrep ci --suppress-errors

GitLab CI/CD

semgrep:
  image: semgrep/semgrep
  script: semgrep ci --suppress-errors

Jenkins

steps {
    sh 'pip3 install semgrep'
    sh 'semgrep ci --suppress-errors'
}

BitBucket Pipelines

script:
  - semgrep ci --suppress-errors

CircleCI

steps:
    - checkout
    - run:
        name: "Semgrep scan"
        command: semgrep ci --suppress-errors

Buildkite

commands:
    - semgrep ci --suppress-errors