This article explains how Vibgrate combines different sources of settings so you can predict a scan's behavior. It is for developers and CI maintainers who configure Vibgrate in more than one place.
Overview
A single scan can be influenced by several sources: the committed configuration file created by vg init, command-line flags, and values supplied through the environment (such as a DSN secret). Understanding how these interact prevents surprises when a local run and a CI run behave differently.
The general model
- The committed configuration file establishes your project's baseline behavior: thresholds, scanner toggles, and exclusions. It applies to every scan automatically.
- Command-line flags express intent for a specific run. For example,
--drift-budget 60or--exclude vendorapply to that invocation. - Environment-provided values are typically used to inject secrets, like a DSN passed via
--dsn "$VIBGRATE_DSN", rather than to change scan scope.
A worked example
Suppose your configuration enables the extended scanners and excludes generated directories. For a one-off check you want a stricter gate, so you add a flag for that run:
vg scan --drift-budget 50
The committed configuration still governs which scanners run and what is excluded; the flag adds the budget for this run only. Nothing about the committed config changes.
Avoiding surprises
- Keep durable decisions (scope, scanner toggles) in committed configuration so they are reviewed and shared.
- Use flags for run-specific intent and experiments.
- Use the environment only for secrets, and keep those out of source control.
Related
See the .vibgrate config guide, the Configuration reference, the environment-variables article, and the per-repository configuration guide.