Add Vibgrate to a GitHub Actions Workflow

Adding the Vibgrate CLI to GitHub Actions means every push and pull request is checked for upgrade drift automatically, so your team sees the DriftScore trend without anyone running a scan by hand. Upgrade drift accumulates quietly: a dependency falls a few major versions behind, a runtime nears end of life, a config pattern goes stale. By the time someone tries to upgrade, the change is large and risky. Running the scanner in CI turns that invisible debt into a number on every commit, which is the first step toward keeping it under control. This tutorial wires a minimal workflow that runs the CLI with npx and scans the checked-out repository, with no global install to maintain.

Prerequisites

• A GitHub repository with a Node.js project and a committed lockfile.
• Permission to add files under .github/workflows.
• Actions enabled for the repository.

Steps

1. Add a workflow file

Create .github/workflows/vibgrate.yml. GitHub picks up any YAML file in this directory as a workflow and runs it on the events you list.

name: Vibgrate Drift Scan
on:
  push:
  pull_request:
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:

2. Check out the repository

The scanner reads your source and lockfile from disk, so check out the code and set up Node first. Pinning a Node version keeps results reproducible across runs.

      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

3. Run the Vibgrate scan

Use the no-install form so you do not have to manage a global install. Bare scan analyzes the working directory, which in CI is the checked-out repository.

npx @vibgrate/cli scan

The scan prints a DriftScore from 0 to 100 along with the findings that drove it. Higher scores mean more accumulated upgrade drift. On the first run, treat the number as your starting point rather than a pass or fail.

4. Trigger on push and PR

The on: block above already runs the job on every push and pull request. This is the recommended starting point: it gives you a DriftScore on the default branch and on each PR branch, so you can compare a proposed change against the baseline the team merges into.

5. Read the DriftScore in logs

Open the workflow run in the Actions tab and expand the scan step. The DriftScore and a summary of findings appear in the step output. From here you can layer on quality gates with --fail-on or a --drift-budget, or route findings into the Security tab with SARIF.

Verification

Push a commit and open the Actions tab. The drift job should complete and the scan step should print a DriftScore. A bare vg scan that finds no blocking issues exits 0, so the job is green. If the job is unexpectedly red, expand the step and read the exit message before changing anything else.

npx @vibgrate/cli scan

Next Steps

• Turn the scan into a quality gate with vg scan --drift-budget to gate pull requests.
• Upload findings to GitHub code scanning with vg scan --format sarif.
• Push results to Vibgrate Cloud from CI with vg scan --push for trend analysis.
• Add a nightly scheduled run so drift is tracked even on quiet days.