CI Integration

Run PipeGuard as a quality gate in your CI/CD pipeline.

Exit Codes

PipeGuard uses standard exit codes for CI integration:

Code	Meaning	CI Behavior
`0`	No violations found	Pipeline passes
`1`	Violations found	Pipeline fails (use as quality gate)
`2`	Runtime error	Pipeline fails (bad config, file not found)

GitLab CI

.gitlab-ci.ymlpipeguard-scan:
  stage: test
  image: golang:1.23-alpine
  before_script:
    - go install github.com/tazi06/pipeguard/cmd/pipeguard@latest
  script:
    - pipeguard scan . --format sarif --output pipeguard.sarif
    - pipeguard scan . --severity critical,high
  artifacts:
    reports:
      sast: pipeguard.sarif
    when: always
  allow_failure: false

This configuration:

Installs PipeGuard from source using go install
Generates a SARIF report and uploads it as a GitLab SAST artifact
Fails the pipeline if critical or high violations are found

Using curl installer

.gitlab-ci.ymlpipeguard-scan:
  stage: test
  image: alpine:3.20
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://pipeguard.dev/install.sh | sh
  script:
    - pipeguard scan .gitlab-ci.yml --severity critical,high

GitHub Actions

.github/workflows/pipeguard.ymlname: PipeGuard Scan

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install PipeGuard
        run: curl -fsSL https://pipeguard.dev/install.sh | sh

      - name: Scan pipeline files
        run: pipeguard scan . --format sarif --output results.sarif

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

      - name: Quality gate
        run: pipeguard scan . --severity critical,high

This configuration:

Installs PipeGuard using the curl installer
Generates a SARIF file and uploads it to GitHub Code Scanning
Results appear in the Security tab of your repository
Fails the workflow if critical/high violations exist

Jenkins Pipeline

Jenkinsfilepipeline {
    agent any
    stages {
        stage('PipeGuard Scan') {
            steps {
                sh 'curl -fsSL https://pipeguard.dev/install.sh | sh'
                sh 'pipeguard scan Jenkinsfile --format json --output pipeguard.json'
                sh 'pipeguard scan Jenkinsfile --severity critical,high'
            }
            post {
                always {
                    archiveArtifacts artifacts: 'pipeguard.json'
                }
            }
        }
    }
}

Pre-commit Hook

Run PipeGuard before every commit:

shell# .git/hooks/pre-commit
#!/bin/sh
pipeguard scan . --severity critical --no-color
if [ $? -ne 0 ]; then
  echo "PipeGuard: critical violations found, commit blocked."
  exit 1
fi

shell$ chmod +x .git/hooks/pre-commit

SARIF Upload

PipeGuard generates SARIF v2.1.0 reports compatible with:

GitHub Code Scanning — Appears in the Security tab
GitLab SAST — Upload as artifact under reports.sast
Azure DevOps — Use the SARIF SAST Scans Tab extension
SonarQube — Import via the SARIF plugin

Tip: Generate SARIF for reporting and use --severity for the quality gate in separate commands. This way you always get the full report even when the gate fails.

Best Practices

Use --format sarif for machine-readable reports and uploads
Use --severity critical,high as the quality gate (not all severities)
Run PipeGuard early in the pipeline before build stages
Use --fix locally to remediate before pushing
Pin a specific PipeGuard version in CI for reproducibility