Troubleshooting Vibgrate Failures in CI

This article helps you understand and fix Vibgrate failures in continuous integration. It is for developers whose pipeline turned red on a Vibgrate step. For pipeline setup, see the CI integration guides.

First, is it a gate or an error?

A failing build can mean Vibgrate worked correctly and the drift gate fired, or that something genuinely went wrong. Gates are intentional. If you configured a budget, exceeding it is supposed to fail the build:

vg scan --drift-budget 60
vg scan --fail-on error

Check the exit code against the Exit Codes reference to tell a gate failure from an operational error.

The gate fired (expected)

If drift exceeded your threshold, the fix is to address the drift or, deliberately, to adjust the budget in a reviewed pull request. Use a baseline so the gate measures change rather than absolute state:

vg scan --baseline .vibgrate/baseline.json

Authentication failures on upload

If the failing step is the upload, the cause is usually credentials. In CI, use a DSN token created with vg dsn create and stored as a secret, not the interactive login. See the auth troubleshooting article.

The checkout directory is wrong

If the scan reports no projects in CI but works locally, the runner's working directory may differ from your checkout. Point the CLI explicitly:

vg scan --cwd $CI_PROJECT_DIR

Network-restricted runners

If the runner cannot reach the network, keep the scan local and only allow egress for the upload step:

vg scan --offline

Reduce noise

Quiet mode keeps logs readable while you debug:

vg scan --quiet

Related

• Exit Codes reference
• Troubleshooting auth and login
• CI integration guides and the vg scan command page