Sample continuous integration (CI) configurations
This document provides sample configuration snippets to run Semgrep CI on various continuous integration (CI) providers.
Feature support
Support for certain features of Semgrep AppSec Platform depend on your CI provider or source code management tool (SCM). The following table breaks down the features and their availability:
Integrations with source code providers, dependent on CI provider:
Feature | GitHub with GitHub Actions | GitLab with GL CI/CD | GitHub, GitLab, or BitBucket with other CI providers |
---|---|---|---|
Diff-aware scanning | ✅ | ✅ | ✅ (May need additional set up) |
Hyperlinks | ✅ | ✅ | ✅ (May need additional set up) |
PR or MR comments | ✅ | ✅ | ✅ (May need additional set up) |
SCM security dashboard | ✅ GitHub Advanced Security Dashboard | ✅ GitLab Security Dashboard | ❌ No |
For example, if you use CircleCI as your CI provider on a GitHub repository, Semgrep AppSec Platform does not have any support for GitHub Advanced Security Dashboard.
The following list defines the above features.
- Diff-aware scanning
- Semgrep AppSec Platform can scan only changes in files when running on a pull or merge request (PR or MR). This keeps the scan fast and reduces finding duplication.
- Hyperlinks to code
- Semgrep AppSec Platform collects findings in a Findings page. In this page, you can click on a finding to return to your SCM (Github, GitLab, or Bitbucket) to view the lines of code in your repository that generated the finding.
- Receiving results (findings) as PR or MR comments
- This feature enables you to receive PR or MR comments from Semgrep AppSec Platform on the lines of code that generated a finding.
- SCM security dashboard
- Send Semgrep findings to your SCM's security dashboard.
GitHub Actions
To add a Semgrep configuration file in your GitHub Actions pipeline:
- Create a
semgrep.yml
file in.github/workflows
in the repository you want to scan. - Copy the relevant code snippet provided in Sample GitHub Actions configuration file.
- Paste the relevant code snippet to
semgrep.yml
file. This is your Semgrep configuration file for GitHub Actions. - Commit the configuration file under
/REPOSITORY-ROOT-DIRECTORY/.github/workflows/semgrep.yml
. - The Semgrep job starts automatically upon detecting the committed
semgrep.yml
file.
If you are self-hosting your repository, you must use a self-hosted runner.
Sample GitHub Actions configuration file
- Default
- Semgrep OSS
The following configuration creates a CI job that runs scans depending on what products you have enabled in Semgrep AppSec Platform.
# 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 }}
You can run specific product scans by passing an argument, such as --supply-chain
. View the list of arguments.
The following configuration creates a CI job that runs Semgrep OSS scans using rules configured for your programming language.
# Name of this GitHub Actions workflow.
name: Semgrep OSS scan
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-oss/scan
# 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 scan" command on the command line of the docker image.
- run: semgrep scan --config auto
You can customize the scan by entering custom rules or other rulesets to scan with. See Scan your codebase with a specific ruleset.
If you define both branches
or branches-ignore
and paths
or paths-ignore
, the workflow only runs when both filters are satisfied.
For example, if your configuration file includes the following definition, the workflow runs only if there are changes on the development
branch to .github/workflows/semgrep.yml
:
push:
branches:
- development
paths:
- .github/workflows/semgrep.yml
Upload findings to GitHub Advanced Security Dashboard
Alternate job that uploads findings to GitHub Advanced Security Dashboard
# 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 --sarif > semgrep.sarif
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 }}
- name: Upload SARIF file for GitHub Advanced Security Dashboard
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: semgrep.sarif
if: always()
GitLab CI/CD
To add a Semgrep configuration snippet in your GitLab CI/CD pipeline:
- Create or edit your
.gitlab-ci.yml
file in the repository you want to scan. - Copy the relevant code snippet provided in Sample GitLab CI/CD configuration snippet, and then paste it to your
.gitlab-ci.yml
file. - Commit the updated
.gitlab-ci.yml
file. - The Semgrep job starts automatically upon detecting the committed
.gitlab-ci.yml
file. You can also view the job from your GitLab project's CI/CD > Pipelines page.