CI/CD recipes

Pepper exposes drop-in pipeline templates for the major CI systems. Each template uploads the source, polls until the scan finishes, downloads SBOMs, signs them with cosign, and fails the build when the project's build gate is breached.

Issue an API key

Pipelines authenticate with an API key (Settings → API Keys → Create), which produces a one-shot token like ppr_xxxxxxxxxxxxxxxxxxxxxxxx. Store it as a CI secret:

GitHub: Repository → Settings → Secrets and variables → Actions
GitLab: Project → Settings → CI/CD → Variables (mark "Masked" + "Protected")
Jenkins: Manage Jenkins → Credentials → Secret text

You will also need PEPPER_API_URL (your Pepper base URL).

Download a ready-to-use template

Every Pepper instance hosts the latest templates at /api/cicd-templates/<platform>:

curl -sL https://pepper.your-org.com/api/cicd-templates/github               -o .github/workflows/pepper.yml
curl -sL https://pepper.your-org.com/api/cicd-templates/gitlab               -o .gitlab-ci.pepper.yml
curl -sL https://pepper.your-org.com/api/cicd-templates/jenkins              -o Jenkinsfile
curl -sL https://pepper.your-org.com/api/cicd-templates/azure-devops         -o azure-pipelines.pepper.yml          # Linux agents
curl -sL https://pepper.your-org.com/api/cicd-templates/azure-devops-windows -o azure-pipelines.pepper.windows.yml  # Windows agents

How the templates work

Every template embeds the same scan script, which you can also read or run on its own: /ci/pepper-scan.sh (sh + curl + jq + tar) and /ci/pepper-scan.ps1 (Windows PowerShell 5.1+). It archives the checkout, uploads it to POST /api/scans, waits for the scan, prints the counts and a link, and fails the job when the build gate fails.

Variable	Meaning
`PEPPER_API_URL`, `PEPPER_API_KEY`	Required. Keep the key in the CI secret store.
`PEPPER_PROJECT`	Project to reuse on every run (the templates pass the repository name), so history and trends build up in one project.
`PEPPER_SCAN_TYPE`	`FULL` (default), `SAST_ONLY`, `SCA_ONLY`, `SECRETS_ONLY`, `IAC_ONLY`.
`PEPPER_TIMEOUT_MINUTES`	How long to wait (default 30).
`PEPPER_FAIL_ON_ERROR`	`1` (default) fails the job if the scan errors or times out; `0` only fails on the gate.
`PEPPER_CA_CERT`	CA bundle when Pepper uses an internal certificate. `HTTPS_PROXY` / `NO_PROXY` are honoured.

Exit codes: 0 gate passed · 1 gate failed · 2 configuration or upload problem (e.g. wrong API key) · 3 scan error or timeout.

Azure DevOps Server / Services

Pipelines → Library: create a variable group pepper with PEPPER_API_URL and PEPPER_API_KEY (mark the key secret).
Commit azure-pipelines.pepper.yml (Linux agents) or azure-pipelines.pepper.windows.yml (Windows agents) and create a pipeline from it. Set pool to your agent pool.
To gate pull requests: Repos → Branches → main → Branch policies → Build validation → add the pipeline as Required.

Secret variables are not exported to scripts automatically; the templates map PEPPER_API_KEY explicitly. Failures are reported as pipeline errors via ##vso[task.logissue], and the CycloneDX SBOM is published as the pepper-sbom artifact.

Pre-commit hook

For developer-machine enforcement before code even reaches CI, install the Pepper pre-commit hook:

curl -fsSL https://pepper.your-org.com/api/precommit/install.sh \
  | bash -s -- https://pepper.your-org.com ppr_xxxxxxxxxxxx

See Pre-commit hook for what it scans and how to tune PEPPER_FAIL_ON.

Tune the build gate

Build gates are per-project. The default is 0 CRITICAL, 5 HIGH, 20 MEDIUM, unlimited LOW, fail-on-new=true. Adjust under Settings → Build Gates or via the API:

curl -X PUT \
  -H "Authorization: Bearer $PEPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxCritical":0,"maxHigh":0,"maxMedium":10,"maxLow":-1,"failOnNew":true}' \
  $PEPPER_API_URL/api/settings/build-gates?projectId=<PROJECT_ID>

Set any limit to -1 to mean "unlimited".
failOnNew rejects any finding that wasn't in the previous completed scan — useful for "no-new-issues" policies that don't require fixing the existing backlog all at once.

Branch-event webhooks (alternative to CI scripts)

If you don't want to run the scan inside CI, point your VCS at Pepper's webhook and Pepper will scan PR/MR head commits on its own infrastructure.

GitHub: Repo → Settings → Webhooks → https://pepper.your-org.com/api/webhooks/github. Secret = GitHub webhook secret in Pepper. Events: Pull requests + Pushes. PR open/update → INCREMENTAL (changed files only).
Bitbucket Cloud: Repository settings → Webhooks → https://pepper.your-org.com/api/webhooks/bitbucket. Triggers: repository push, PR created, PR updated. Same incremental behavior.
Azure DevOps: Project settings → Service hooks → Web Hooks → https://pepper.your-org.com/api/webhooks/azure-devops. Events: code pushed, PR created, PR updated. Basic auth password = Pepper secret.
GitLab: Project → Settings → Webhooks → https://pepper.your-org.com/api/webhooks/gitlab. Trigger: merge request events + push events.

Status checks: Pepper does not yet write back a check-run; consume gate status by polling GET /api/scans/<id> as above.