CI Integration

Copy this into your pipeline

VibeGuard runs in any CI system. Output SARIF for GitHub Code Scanning, or JSON for custom integrations. No cloud account required.

2-minute setup

Runs in your runner

Standard SARIF output

Why scan in CI?

Local scans catch issues before you commit. CI scans catch what slips through - and make sure every PR meets the same bar.

Consistency

Every commit gets checked. Not just when you remember to run the scan.

Gate deployments

Block merges when critical issues are found. No manual review of scan results required.

Track over time

Baselines let you see if security is improving or regressing across releases.

Team visibility

Findings show up in GitHub's Security tab. Everyone sees the same results.

What is SARIF?

SARIF (Static Analysis Results Interchange Format) is a standard file format for static analysis output. Think of it like JSON, but with a specific structure that tools understand.

When you output SARIF:

GitHub can display findings in the Security tab
Findings link directly to the relevant line of code
PR comments show inline with the code changes
Results from multiple tools merge into one view

GitHub explicitly supports uploading SARIF from third-party tools. VibeGuard is one of many tools that can output this format.

GitHub Actions

This workflow runs on every push and PR to main, then uploads findings to GitHub Code Scanning. Copy this file to .github/workflows/.

.github/workflows/vibeguard.yml

name: VibeGuard Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install VibeGuard
        run: pip install vibeguard-cli

      - name: Run security scan
        run: vibeguard scan . --format sarif --output results.sarif

      - name: Upload SARIF to GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

What happens: The workflow checks out your code, installs VibeGuard, runs a scan, and uploads the SARIF file. Findings appear in the Security tab within a few seconds.

Note: The github/codeql-action/upload-sarif action is the official GitHub action for uploading SARIF files. It works with any tool that outputs SARIF, not just CodeQL.

How to fail builds

VibeGuard uses exit codes to signal whether the build should pass or fail. This is the standard way CI systems decide what to do next.

exit 0

Pass

No critical or high findings

exit 1

Warning

Medium findings detected

exit 2

Fail

Critical or high findings detected

Customize thresholds with flags:

vibeguard scan . --fail-on high --warn-on mediumvibeguard scan . --fail-on critical # Only fail on criticalvibeguard scan . --fail-on none # Never fail (report only)

Why warnings exist: Sometimes you want to surface medium issues without blocking the build. Warnings show up in logs but don't stop the pipeline.

Baselines: only fail on new findings

When you adopt VibeGuard on an existing codebase, you might have legacy findings you can't fix today. That's normal.

The problem

You run your first scan and get 47 findings. You can't fix them all before the next release. But you also don't want new issues slipping in while you work through the backlog.

The solution

vibeguard baseline create

Snapshot your current findings. This creates a baseline file.

vibeguard scan . --baseline

Only report findings not in the baseline. Old issues are tracked separately.

vibeguard baseline update

As you fix legacy issues, update the baseline to reflect your progress.

This way, CI only fails on newly introduced issues. You make progress on technical debt without blocking current work.

PR-specific scanning

For pull requests, you often want to scan only the changes - not the entire codebase. This is faster and shows only relevant findings.

.github/workflows/vibeguard-pr.yml

name: PR Security Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for baseline comparison

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install VibeGuard
        run: pip install vibeguard-cli

      - name: Run scan with baseline
        run: vibeguard scan . --baseline --format sarif --output results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
          category: vibeguard-pr

Push scanning

Runs on every commit to main. Full scan of the codebase. Results feed into your baseline tracking.

PR scanning

Runs on PR open/update. Uses baseline to show only new findings. Faster feedback for developers.

Making it fast

Security scans shouldn't slow down your pipeline. Here's how to keep VibeGuard fast.

Cache pip packages

- name: Cache pip packages
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-vibeguard
    restore-keys: |
      ${{ runner.os }}-pip-

- name: Install VibeGuard
  run: pip install vibeguard-cli

Exclude paths

--exclude node_modules,dist,.git

Skip directories that don't need scanning

Target specific scanners

--scanners secrets,deps

Run only the scanners you need

Parallel jobs

--parallel 4

Run scanners in parallel (default: auto)

Typical scan times: Small projects (under 10k lines): 10-30 seconds. Medium projects (10k-100k lines): 30-90 seconds. Large projects: depends on scanner selection and exclusions.

Other CI systems

VibeGuard is just a CLI. If you can run pip install and shell commands, it works.

GitLab CI

security-scan:
  image: python:3.11
  script:
    - pip install vibeguard-cli
    - vibeguard scan . --format json --output results.json
  artifacts:
    reports:
      sast: results.json

GitLab can consume the JSON output as a SAST artifact. Findings appear in the Security Dashboard.

Jenkins

pipeline {
    agent any
    stages {
        stage('Security Scan') {
            steps {
                sh 'pip install vibeguard-cli'
                sh 'vibeguard scan . --format json --output results.json'
            }
        }
    }
}

Archive the JSON output as a build artifact. Use the Warnings NG plugin for inline annotations.

CircleCI, Azure DevOps, Bitbucket Pipelines, etc.

Same pattern: install Python, pip install vibeguard-cli, run the scan. Output JSON or SARIF depending on what your platform supports. Check the docs for platform-specific examples.

Common CI issues

SARIF upload fails with 'invalid format'

Make sure you're using --format sarif (not --format json). The SARIF file needs specific fields that the JSON output doesn't include.

Scan succeeds but no findings in Security tab

Check that you're using the github/codeql-action/upload-sarif action. Also verify the sarif_file path matches what VibeGuard outputs. It can take a few minutes for findings to appear.

Build fails with exit code 2 but I don't see why

Run with --verbose to see detailed output. Or use --format json --output results.json and inspect the file. The finding details will show what triggered the failure.

Scans are slow in CI

Add pip caching (example above). Exclude directories you don't need to scan (node_modules, .git, build outputs). Consider running only specific scanners if you don't need all checks.

Different results locally vs in CI

Usually caused by different Python versions or missing system dependencies for certain scanners. Pin your Python version in CI to match your local environment. Run vibeguard doctor in both environments to compare.

Still stuck? Run vibeguard doctor in your CI environment to check for missing dependencies or configuration issues. The output includes suggestions for common problems.

Add VibeGuard to your pipeline

Security checks on every commit. No cloud account, no manual review.

pip install vibeguard-cli