Quickstart

Five copy-paste steps, from the first scan to a baseline in CI. You need Node.js 22 or newer and a repository to scan. Every command runs locally; nothing is uploaded.

1. Run the first scan

npx @velella/offing scan .

Each finding names its severity, the exact file and line, the replacement, and the source. The first lines look like this on the demo project:

Found 5 lifecycle risks. The most urgent:
  HIGH Unsupported actions/checkout runtime (.github/workflows/ci.yml:9)
  MEDIUM Node.js 18 is end-of-life (package.json:5)
  …

Add --json for machine-readable output, or --format compact for one line per finding when an agent reads the result.

2. Check one dependency before adding it

npx @velella/offing check pkg:npm/request@2.88.2

The command prints the lifecycle problem, the replacement, and the evidence. It exits 1 when a rule at or above --fail-on (default high) applies and 0 otherwise. no-data means Offing has no rule for the package, not that it is safe.

3. Read the evidence for one finding

Take a finding id from step 1 and inspect it:

npx @velella/offing explain '<finding-id>' .

For structured context an agent can follow, including affected files, usages, constraints, and verification commands:

npx @velella/offing context '<finding-id>' . --json

Offing suggests verification commands; it never runs migration commands for you.

4. Add the check to CI

Create .github/workflows/offing.yml:

name: Offing

on:
  pull_request:

permissions:
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: velella-sh/offing@v0.7.1
        with:
          fail-on-severity: high

The action annotates the pull request, can upload SARIF to code scanning, and fails the job on a finding at or above the chosen severity. See the GitHub Action guide for inputs, permissions, and artifacts.

5. Add a baseline

Accept the findings you already know about, then report only new regressions:

npx @velella/offing baseline .
npx @velella/offing scan . --baseline .offing-baseline.json

Commit .offing-baseline.json. The action reads the same file with baseline: .offing-baseline.json.

Next

• Install Offing on every channel
• Use it with an agent through the Agent Skill or the local MCP server
• Lifecycle rules and the evidence policy
• Contribute