Dependency management policy

Overview

Kausa uses Dependabot for automated dependency updates and pnpm audit as a CI gate. This keeps the supply chain current and blocks PRs that introduce HIGH or CRITICAL advisories.

How Dependabot is configured

Dependabot runs weekly and opens PRs in three groups:

• Security updates — patches for known advisories, ungrouped by severity.
• Production dependencies — minor and patch bumps grouped together.
• Dev dependencies — all update types grouped together.

GitHub Actions versions are also tracked weekly.

Ignored major bumps

React, React DOM, and Next.js major versions are ignored by Dependabot. These frameworks require migration guides and manual testing, so they go through a dedicated upgrade PR reviewed by the maintainer.

PR labels

All Dependabot PRs carry the deps and security labels for filtering.

CI audit gate

Two workflows enforce the audit:

1. audit.yml — standalone workflow, runs on every PR and push to main. Executes pnpm audit --audit-level=high. A non-zero exit code (any HIGH or CRITICAL advisory) fails the check.
2. build-check.yml — the existing build pipeline also runs the same audit step before the production build. Belt and suspenders: even if audit.yml is somehow skipped, the build check still catches it.

Only HIGH and CRITICAL advisories block the pipeline. Moderate and low findings are logged but do not fail the check — they produce too much noise from transitive dependencies outside our control.

Handling a red audit check

When the audit step fails on a PR:

1. Run locally: pnpm audit --audit-level=high to see the advisory details.
2. Check if it's fixable: pnpm audit --fix may resolve it by bumping a transitive dependency.
3. Check upstream: if the advisory is in a transitive dep, check whether the direct dependency has a newer version that pulls in the fix.
4. If no fix exists yet: open an issue tracking the advisory. If the risk is accepted for a limited time, you can add an overrides entry in package.json to pin the safe version, or use pnpm audit --ignore <advisory-id> in CI (document why in the PR).
5. Never suppress the gate permanently. Every override or ignore must have a tracking issue and a review date.

Running locally

# Check for all advisories
pnpm audit

# Check only HIGH and CRITICAL (matches CI)
pnpm audit --audit-level=high

# Attempt automatic fix
pnpm audit --fix

When to temporarily disable Dependabot

Disable Dependabot (by removing the ecosystem entry from .github/dependabot.yml) only when:

• A major framework migration is in progress and Dependabot PRs would conflict.
• The repo is in a code freeze for a release.

Re-enable it as soon as the freeze or migration ends. Never leave it disabled for more than two weeks without a tracking issue.

Escalation

If an advisory cannot be resolved within 48 hours:

1. File an issue with the security label.
2. Notify the maintainer.
3. Document the risk and any temporary mitigations in the issue.