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

Configuring blocking findings and errors in continuous integration (CI)

This article documents how Semgrep in CI pipelines handles 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 blocks the pull requests (PRs) or merge requests (MRs) in its default configuration only when it matches a blocking finding.

Blocking findings can be defined as:

  • Findings defined in the Policies page of Semgrep Cloud Platform. Avoid blocking findings by removing rules from the Block rule mode of the Policies page.
  • If you do not use Semgrep Cloud 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. Semgrep suppresses all errors and does not surface them to the CI provider. 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.

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 optionDescription
semgrep ci or semgrep ci --suppress-errorsDefault: CI fails on blocking findings, CI passes on internal errors.
semgrep ci --no-suppress-errorsCI fails on blocking findings, CI fails on internal errors.
semgrep ci || trueCI 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 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: 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 Cloud Platform through your SEMGREP_APP_TOKEN.
          # Generate a token from Semgrep Cloud 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@v3
  - 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:

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

Find what you needed in this doc? Join the Semgrep Community Slack group to ask the maintainers and the community if you need help, or check out other ways to get help.