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.
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.
- 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 code0
(success). Consequently, Semgrep in CI does not report other statuses than0
or1
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 if there are changes to .github/workflows/semgrep.yml:
push:
branches:
- main
- master
paths:
- .github/workflows/semgrep.yml
# 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
- GitLab CI/CD
- Jenkins
- BitBucket Pipelines
- CircleCI
- Buildkite
steps:
- uses: actions/checkout@v4
- name: Scan and suppress internal errors
run: semgrep ci --suppress-errors
semgrep:
image: semgrep/semgrep
script: semgrep ci --suppress-errors
steps {
sh 'pip3 install semgrep'
sh 'semgrep ci --suppress-errors'
}
script:
- semgrep ci --suppress-errors
steps:
- checkout
- run:
name: "Semgrep scan"
command: semgrep ci --suppress-errors
commands:
- semgrep ci --suppress-errors
Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.