> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semgrep.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling blocking findings and errors

> This article documents how Semgrep handles blocking findings and errors and how you can change Semgrep's default behavior.

## Blocking findings

Blocking findings are those identified by Semgrep Code using rules defined in Semgrep AppSec Platform's [Policies page](https://semgrep.dev/orgs/-/policies) and are set to **Block** mode. You can avoid blocking findings by removing rules or by switching the rule mode to **Monitor**, **Comment**, or **Disabled**.

If you do **not** use Semgrep AppSec Platform with Semgrep in CI or Semgrep Managed Scans (that is, you are using a **stand-alone setup**), all Semgrep findings are blocking findings. The existence of any findings means that Semgrep returns an exit code of `1`, which you can use to block your PRs or MRs.

## Semgrep's default behavior regarding blocking findings and errors

When Semgrep identifies one or more blocking findings, it returns exit code `1`. You can use this result to set up additional checks to enforce a block in your CI/CD pipeline, such as not allowing the merge of the PR/MR. This action applies to both full scans and <Tooltip tip="A diff-aware scan shows only findings caused by changes in files starting from a specific Git baseline. It is typically performed on feature branches when a pull request or merge request is opened. Unlike full scans, diff-aware scans only consider changes within modified files. Cross-file analysis is not supported for diff-aware scans." cta="See full definition." href="/semgrep-code/glossary#diff-aware-scan">diff-aware scans</Tooltip>.

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.

If Semgrep encounters an internal error, it sends an anonymous crash report to a crash-reporting server and returns exit code 0. If you want to catch internal errors, review the [CLI reference](/cli-reference#exit-codes) for more information about Semgrep's exit codes and the options explained in this article to determine how you want to handle each exit code.

## Configuration options for blocking findings and errors in CI

You can configure, change, or revert to the default setup of blocking findings and errors in your CI pipeline by passing one of the following options in the `semgrep.yml` file used to configure and run Semgrep in your CI pipeline:

| CI option                                      | Description                                                                    |
| :--------------------------------------------- | :----------------------------------------------------------------------------- |
| `semgrep ci` or `semgrep ci --suppress-errors` | Default. CI **fails** on blocking findings, but **passes** on internal errors. |
| `semgrep ci --no-suppress-errors`              | CI **fails** on blocking findings and internal errors.                         |
| <code>semgrep ci \|\| true</code>              | CI **passes** on blocking findings and internal errors.                        |

To change Semgrep's behavior, modify your pipeline or job file, specifically the `semgrep ci` command, to the CI option that best fits your needs. For example, GitHub users should edit the `semgrep.yml` workflow file and include the following under the `run` key:

```yaml theme={null}
run:
    semgrep ci --suppress-errors
```

GitLab users would include the following under the `script` key:

```yaml theme={null}
script:
    semgrep ci --suppress-errors
```

If you use any other CI provider, refer to its documentation for information on where to provide this information. Additionally, see the sample configurations in the following section.

## Sample configurations for blocking findings and errors

The following is a sample `.semgrep.yml` file you can use with GitHub Actions. Semgrep's default behavior regarding blocking findings and errors applies here:

* Semgrep returns exit code `1` if there are blocking findings
* Semgrep returns exit code `0` if there are *no* blocking findings, even if there are internal errors. Semgrep does, however, send an anonymous report to the crash-reporting server.

This means that, by default, Semgrep doesn't report statuses other than `0` or `1`.

```yaml expandable theme={null}
# 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.

permissions:
  contents: read

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 }}
```

Optionally, you can explicitly indicate that Semgrep is using the default settings by including the `--suppress-errors` flag. The modified portion of the configuration file is as follows:

```yaml theme={null}
steps:
  - uses: actions/checkout@v6
  - name: Scan and suppress internal errors
    run: semgrep ci --suppress-errors
```

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

<Tabs>
  <Tab title="BitBucket Pipelines">
    ```yaml theme={null}
    script:
      - semgrep ci --suppress-errors
    ```
  </Tab>

  <Tab title="Buildkite">
    ```yaml theme={null}
    commands:
        - semgrep ci --suppress-errors
    ```
  </Tab>

  <Tab title="CircleCI">
    ```yaml theme={null}
    steps:
        - checkout
        - run:
            name: "Semgrep scan"
            command: semgrep ci --suppress-errors
    ```
  </Tab>

  <Tab title="GitHub Actions">
    ```yaml theme={null}
    steps:
    - uses: actions/checkout@v6
    - name: Scan and suppress internal errors
       run: semgrep ci --suppress-errors
    ```
  </Tab>

  <Tab title="GitLab CI/CD">
    ```yaml theme={null}
    semgrep:
      image: semgrep/semgrep
      script: semgrep ci --suppress-errors
    ```
  </Tab>

  <Tab title="Jenkins">
    ```javascript theme={null}
    steps {
        sh 'pipx install semgrep'
        sh 'semgrep ci --suppress-errors'
    }
    ```
  </Tab>
</Tabs>