GitLab CI/CD

1. Add the variable

Create a secret key in Safeguard under Settings → Developer with the scopes scans:trigger and scans:read. In GitLab, add it under Settings → CI/CD → Variables as SAFEGUARD_API_KEY, with Mask variable on. Leave Protect variable off if unprotected branches or merge requests should be scanned.

2. Include the template

Add this to .gitlab-ci.yml:

include:
  - remote: https://registry.safeguard.sh/ci/safeguard.gitlab-ci.yml

safeguard:
  extends: .safeguard-scan
  variables:
    SAFEGUARD_FAIL_ON: critical

The template (view it) defines a hidden .safeguard-scan job in the test stage. It installs the CLI and runs safeguard ci scan --wait. If your pipeline has no test stage, set stage: on the safeguard job.

Choose the branches

On a merge request the source branch is scanned.

Variables

Without the template

safeguard:
  stage: test
  image: alpine:3.20
  variables:
    SAFEGUARD_INSTALL_DIR: /usr/local/bin
  before_script:
    - apk add --no-cache bash curl ca-certificates
    - curl -fsSL https://cli.safeguard.sh/install | bash
  script:
    - safeguard ci scan --wait --fail-on critical
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

Troubleshooting

• The job is missing from the pipeline. The branch does not match SAFEGUARD_BRANCH_PATTERN, or the pipeline has no test stage.
• AUTHENTICATION_REQUIRED on a merge request or branch. The variable is protected, so GitLab passes it only to protected branches.
• Other errors: see Troubleshooting.