Set up reusable GitHub workflows for Semgrep scans
Reusable workflows allow you to simplify the process of configuring .github/workflows/semgrep.yml
files for each of your repositories. You define a workflow once in a central repository, then reuse it in workflows in other repositories. This avoids duplication and makes maintenance easier.
Reusable workflows can be triggered by several types of events, including push, pull request, and schedule. This makes them relatively flexible compared to repository rulesets. Repository rulesets or branch protection rules can only be triggered by pull request event types.
Set up a reusable workflow
- Create a new repository to hold your reusable workflow, and add a
.github/workflows/semgrep.yml
file. - Add the job configuration to
semgrep.yml
underjobs:
. You can use the job definition from the recommended snippet or your current job configuration. - Under the
on:
key, addworkflow_call
. This defines the condition to trigger the job described in the reusable workflow: when another repository calls it. Other keys underon:
are optional for the reusable workflow. - In each repository where you want your reusable workflow called, create or update the
semgrep.yml
file to call the reusable workflow. To do this, includeuses
under thejobs:
key as shown in the following sample configuration.
name: Semgrep
on:
# Scan changed files in PRs (diff-aware scanning):
pull_request: {}
# Scan on-demand through GitHub Actions interface:
workflow_dispatch: {}
# Schedule the CI job (this method uses cron syntax):
schedule:
# Please change the cron schedule to a random time to avoid load spikes on GHA.
- cron: '24 13 * * *' # Sets Semgrep to scan every day at 13:24 UTC.
jobs:
call-semgrep:
uses: {ORG}/{REPO}/.github/workflows/semgrep.yml@main
secrets: inherit
When using this sample configuration, be sure to update the schedule under on
to a random time, and set repository details and path for the reusable workflow under jobs
to match where you stored your reusable workflow.
The secrets: inherit
line passes the secrets from the calling workflow to the called workflow, so each calling repository must also have a SEMGREP_APP_TOKEN
secret added. GitHub does not currently support passing secrets from a central reusable workflow (the called workflow) to the calling workflows.
Run a scan
Once you've configured the workflows for your repositories, the reusable workflow is called whenever a triggering event occurs, such as when a developer opens a pull request or commits a change.
Limitations
As described in Set up a reusable workflow, you must create a .github/workflows/semgrep.yml
file for each repository to call the reusable workflow and add a SEMGREP_APP_TOKEN
secret to the repository. This is in contrast to repository rulesets, which only require the central workflow file to be added.
Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.