|
| 1 | +# Dependency Update Policy |
| 2 | + |
| 3 | +Last Updated: 2026-03-29 |
| 4 | +Owner: Repository maintainers |
| 5 | +Linked issue: `#148` (OPS-18) |
| 6 | + |
| 7 | +## Purpose |
| 8 | + |
| 9 | +This document defines the dependency update automation policy and security-advisory triage workflow for Taskdeck. It complements the existing vulnerability management policy (`docs/security/SECURITY_DEPENDENCY_VULNERABILITY_POLICY.md`) by adding proactive update automation and structured triage ownership. |
| 10 | + |
| 11 | +Related docs: |
| 12 | + |
| 13 | +- `docs/security/SECURITY_DEPENDENCY_VULNERABILITY_POLICY.md` — vulnerability scan cadence, severity policy, exception process |
| 14 | +- `.github/dependabot.yml` — Dependabot automation configuration |
| 15 | + |
| 16 | +## Automation Tool |
| 17 | + |
| 18 | +Taskdeck uses **GitHub Dependabot** for automated dependency update PRs across three ecosystems: |
| 19 | + |
| 20 | +| Ecosystem | Config directory | Schedule | Grouping strategy | |
| 21 | +|----------------|---------------------------|-----------------|--------------------------------------------| |
| 22 | +| NuGet (backend)| `/backend` | Weekly (Monday) | Minor/patch grouped; major individual | |
| 23 | +| npm (frontend) | `/frontend/taskdeck-web` | Weekly (Monday) | Minor/patch grouped; major individual | |
| 24 | +| GitHub Actions | `/` | Weekly (Monday) | All update types grouped | |
| 25 | + |
| 26 | +## Update Categories |
| 27 | + |
| 28 | +### Routine updates (minor and patch) |
| 29 | + |
| 30 | +- Grouped into single PRs per ecosystem to reduce noise. |
| 31 | +- Expected to pass CI without intervention in most cases. |
| 32 | +- Maintainer review is required before merge; no auto-merge is enabled. |
| 33 | +- If CI passes and the changelog shows no breaking changes, merge promptly. |
| 34 | + |
| 35 | +### Major version updates |
| 36 | + |
| 37 | +- Arrive as individual PRs for explicit review. |
| 38 | +- Require maintainer assessment of breaking changes, migration guides, and downstream impact. |
| 39 | +- Should be tested locally when the changelog indicates API surface changes. |
| 40 | +- Target resolution within one development cycle (1 to 2 weeks) unless blocked. |
| 41 | + |
| 42 | +### Security updates |
| 43 | + |
| 44 | +- Dependabot security updates are enabled by default on GitHub and create PRs independently of the weekly schedule. |
| 45 | +- Security PRs are distinguishable by the security advisory reference in the PR body. GitHub may also auto-apply a `security` label if one exists in the repo. Note: the PR title format is the same as regular Dependabot PRs ("Bump X from Y to Z"), so rely on the body and labels rather than the title to identify security updates. |
| 46 | +- Security updates follow the severity-based SLA targets defined below. |
| 47 | + |
| 48 | +### Lock-file-only updates |
| 49 | + |
| 50 | +- Dependabot may propose lock-file-only changes when transitive dependencies have updates. |
| 51 | +- These follow the same review process as routine updates. |
| 52 | +- Pay attention to transitive security fixes surfaced through lock-file changes. |
| 53 | + |
| 54 | +## PR Verification Expectations |
| 55 | + |
| 56 | +All Dependabot PRs must pass the `ci-required.yml` gate before merge. This includes: |
| 57 | + |
| 58 | +- Backend build and unit tests (domain, application, CLI, API integration) |
| 59 | +- Frontend typecheck, lint, unit tests, and E2E smoke |
| 60 | +- Architecture boundary tests |
| 61 | +- Docs governance checks |
| 62 | + |
| 63 | +Additional verification for dependency PRs: |
| 64 | + |
| 65 | +- Review the Dependabot PR body for changelog links and compatibility notes. |
| 66 | +- For NuGet major bumps: verify `dotnet build` succeeds locally and check for deprecation warnings. |
| 67 | +- For npm major bumps: verify `npm run build` and `npx vitest --run` succeed locally. |
| 68 | +- For GitHub Actions bumps: verify the referenced action version exists and check for breaking changes in the action's release notes. |
| 69 | + |
| 70 | +## Security-Advisory Triage Workflow |
| 71 | + |
| 72 | +### Trigger sources |
| 73 | + |
| 74 | +1. **Dependabot security alerts** — GitHub surfaces these on the Security tab and may auto-create PRs. |
| 75 | +2. **Dependabot security update PRs** — automated fix PRs for known advisories. |
| 76 | +3. **Nightly dependency security signals** — `nightly-quality.yml` runs vulnerability scans on schedule. |
| 77 | +4. **Manual scan** — operators can run `dotnet list ... --vulnerable` and `npm audit` locally (see commands in the vulnerability policy doc). |
| 78 | + |
| 79 | +### Triage ownership |
| 80 | + |
| 81 | +- The maintainer who sees the alert first owns initial triage classification. |
| 82 | +- Classification means: confirm severity, determine if the package is runtime/test/build-only, and assign a remediation owner. |
| 83 | +- If no maintainer is available within the SLA window, the alert must be escalated (GitHub issue with `Priority I` or `Priority II` label). |
| 84 | + |
| 85 | +### Severity-based response targets |
| 86 | + |
| 87 | +These targets align with the existing vulnerability policy (`docs/security/SECURITY_DEPENDENCY_VULNERABILITY_POLICY.md`): |
| 88 | + |
| 89 | +| Severity | Triage SLA | Remediation target | |
| 90 | +|----------|---------------------|-------------------------------------------------------| |
| 91 | +| Critical | Same business day | Merge fix within 1 business day; block releases | |
| 92 | +| High | 1 business day | Merge fix within 3 business days; block releases | |
| 93 | +| Moderate | 5 business days | Schedule in normal backlog; does not block release | |
| 94 | +| Low/Info | 10 business days | Batch with routine dependency hygiene | |
| 95 | + |
| 96 | +### Triage checklist |
| 97 | + |
| 98 | +For each security advisory or Dependabot security PR: |
| 99 | + |
| 100 | +1. Confirm the advisory applies to Taskdeck's usage of the package (not just presence in the dependency tree). |
| 101 | +2. Classify exposure: `runtime`, `test-only`, `build-only`, `local-dev-only`. |
| 102 | +3. Check if Dependabot has already opened a fix PR. If yes, prioritize review. |
| 103 | +4. If no automated fix exists, create a GitHub issue with the appropriate priority label. |
| 104 | +5. If remediation is blocked (no upstream fix available), follow the exception process in the vulnerability policy doc. |
| 105 | +6. Post triage outcome (fixed, excepted, or false positive) as a comment on the alert or PR. |
| 106 | + |
| 107 | +### Escalation |
| 108 | + |
| 109 | +- Critical/High findings with no available fix: create a GitHub issue with `Priority I` label and document compensating controls. |
| 110 | +- Findings that affect the release pipeline: notify maintainers and block release candidates per the vulnerability policy enforcement rules. |
| 111 | + |
| 112 | +## Policy Boundaries |
| 113 | + |
| 114 | +### What this policy does NOT cover |
| 115 | + |
| 116 | +- Auto-merge: all dependency PRs require human review. Auto-merge may be considered in the future for patch-only grouped updates with passing CI, but is not enabled now. |
| 117 | +- Renovate: the project uses Dependabot only. Renovate may be evaluated if Dependabot proves insufficient. |
| 118 | +- SBOM generation: tracked separately in `#103`. |
| 119 | +- Stricter required-PR blocking for vulnerability findings: tracked as a follow-up in the vulnerability policy doc. |
| 120 | + |
| 121 | +### Review cadence |
| 122 | + |
| 123 | +- Maintainers should review open Dependabot PRs at least weekly (aligned with the Monday generation schedule). |
| 124 | +- Stale Dependabot PRs older than 30 days should be investigated: either the update is blocked (needs an issue) or it was overlooked. |
0 commit comments