From efec84a07aaaf48ecfadc7d5efdbe5ae7dcde6fe Mon Sep 17 00:00:00 2001 From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:09:43 +0000 Subject: [PATCH] docs(deps): replace Dependabot version-update policy with Renovate (#51) * docs(deps): replace Dependabot version-update policy with Renovate * docs(deps): reconcile Renovate policy with exact-pin and ruleset names --- aws-infrastructure.md | 8 ++-- cdk-project-layout.md | 6 +-- github-standards.md | 109 +++++++++++++----------------------------- pull-requests.md | 2 +- 4 files changed, 40 insertions(+), 85 deletions(-) diff --git a/aws-infrastructure.md b/aws-infrastructure.md index 5411148..6379176 100644 --- a/aws-infrastructure.md +++ b/aws-infrastructure.md @@ -44,13 +44,13 @@ This is the canonical statement; [dev-environment.md](dev-environment.md#nodejs) ## CDK Version Policy -Pin `aws-cdk-lib` to an exact version (no `^`, `~`, or `>=`) and let Dependabot keep it current. There is no static "blessed version" — the org standard is the latest release that passes the gates below. Do not add blanket `dependabot.yml` ignore entries for `aws-cdk-lib`; that is how pins rot into carrying known vulnerabilities. +Pin `aws-cdk-lib` to an exact version (no `^`, `~`, or `>=`) and let Renovate keep it current. There is no static "blessed version" — the org standard is the latest release that passes the gates below. Do not add blanket Renovate ignore rules for `aws-cdk-lib`; that is how pins rot into carrying known vulnerabilities. -Why exact + automated: the exact pin plus the lockfile gives reproducible builds; weekly Dependabot version updates keep the pin moving; CI (`npm ci` + `cdk synth`) and the dependency-review check reject a bad release at the PR. A release with broken bundled-dep metadata (e.g. 2.254.0) fails `npm ci` on its own bump PR; a release bundling a vulnerable transitive dep fails dependency review. Either way, a bad release never merges — the gates do the vetting, not a frozen number in this document. +Why exact + automated: the exact pin plus the lockfile gives reproducible builds; weekly Renovate PRs keep the pin moving; CI (`npm ci` + `cdk synth`) and the dependency-review check reject a bad release at the PR. A release with broken bundled-dep metadata (e.g. 2.254.0) fails `npm ci` on its own bump PR; a release bundling a vulnerable transitive dep fails dependency review. Either way, a bad release never merges — the gates do the vetting, not a frozen number in this document. -aws-cdk-lib bundles transitive dependencies (`inBundle: true`) that npm `overrides` cannot patch. When a bundled dep has a vulnerability, the only fix is advancing to a release that bundles the patched version — treat the alert as a prompt to merge the next Dependabot bump, never as something to dismiss indefinitely. +aws-cdk-lib bundles transitive dependencies (`inBundle: true`) that npm `overrides` cannot patch. When a bundled dep has a vulnerability, the only fix is advancing to a release that bundles the patched version — treat the alert as a prompt to merge the next Renovate bump, never as something to dismiss indefinitely. -If a specific release is known-bad, ignore that version only (`ignore: - dependency-name: aws-cdk-lib, versions: ["2.254.0"]`) with a comment explaining why, and remove the entry once a fixed release ships. +If a specific release is known-bad, exclude that version only with a `packageRules` entry in the repo's `renovate.json` (`matchPackageNames: ["aws-cdk-lib"], allowedVersions: "!/^2\\.254\\.0$/"`), explain why in the rule's `description` field since `renovate.json` is strict JSON and cannot carry comments, and remove the entry once a fixed release ships. When upgrading, verify on a branch first: diff --git a/cdk-project-layout.md b/cdk-project-layout.md index 7cb4b0b..4418b52 100644 --- a/cdk-project-layout.md +++ b/cdk-project-layout.md @@ -84,16 +84,16 @@ A handful of stacks predate this convention and remain PascalCase (e.g., `SeaHav ## Version Pinning -Pin `aws-cdk-lib` to an exact version (no `^`/`~`/`>=`) and let Dependabot keep it current — no blanket ignore entries. See [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy) for the full policy. +Pin `aws-cdk-lib` to an exact version (no `^`/`~`/`>=`) and let Renovate keep it current — no blanket ignore entries. See [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy) for the full policy. -`aws-cdk-lib` bundles transitive dependencies (`inBundle: true`). Certain versions break `npm ci` with phantom missing-package errors that cannot be fixed via npm `overrides`. CI gates Dependabot bumps automatically; when bumping manually, test first: +`aws-cdk-lib` bundles transitive dependencies (`inBundle: true`). Certain versions break `npm ci` with phantom missing-package errors that cannot be fixed via npm `overrides`. CI gates Renovate bumps automatically; when bumping manually, test first: 1. Update `package.json` to the new version 2. Run `rm -rf node_modules package-lock.json && npm install` 3. Run `npm ci` -- if it fails, the version is not safe 4. Run `npx cdk synth` -- if it fails, the version is not safe -Dependabot will flag vulnerabilities in bundled transitive deps. npm `overrides` cannot fix these — the remedy is advancing to the release that bundles the patched version. Merge the next `aws-cdk-lib` bump rather than dismissing the alert. +Dependabot alerts will flag vulnerabilities in bundled transitive deps. npm `overrides` cannot fix these — the remedy is advancing to the release that bundles the patched version. Merge the next `aws-cdk-lib` bump rather than dismissing the alert. See [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy) for more detail. diff --git a/github-standards.md b/github-standards.md index 24692fa..67772f3 100644 --- a/github-standards.md +++ b/github-standards.md @@ -6,9 +6,9 @@ - Every repo gets a one-line description - Every repo gets standard topics and a README badge block (see below) - Default to `private` visibility for org repos -- Dependabot alerts and security updates enabled on all active repos -- Org-level defaults auto-enable alerts and security updates on new repos -- Every repo with dependencies gets a `.github/dependabot.yml` for weekly version updates +- Dependabot alerts enabled on all active repos. Version updates and security-fix PRs come from Renovate, not Dependabot. +- Org-level defaults auto-enable alerts on new repos +- Every repo with dependencies gets a root `renovate.json` that extends the org preset (see [Dependency Updates](#dependency-updates)). Do not add `.github/dependabot.yml`. - Merge settings: enable **auto-merge** and **auto-delete head branch on merge** (`allow_auto_merge` + `delete_branch_on_merge`). These have no org-level default — set them per-repo at provisioning. ## Security & Merge Baseline @@ -22,7 +22,8 @@ Every active repo runs the same baseline. The security half is meant to be carri | `code_security` (advanced security) | enabled | Sea Haven Standard config | | Secret scanning + push protection | enabled | Sea Haven Standard config | | Secret scanning non-provider patterns + validity checks | enabled | per-repo until added to the config | -| Dependabot alerts + security updates | enabled | org auto-enable default + config | +| Dependabot alerts | enabled | org auto-enable default + config | +| Dependabot security-update PRs | disabled once the repo is Interactive in Renovate | per-repo; Renovate opens the CVE fix PR instead | | CodeQL default setup | configured | per-repo (`PATCH .../code-scanning/default-setup state=configured`) until added to the config | Exceptions: @@ -32,85 +33,37 @@ Exceptions: To audit drift: `gh api repos// --jq '{allow_auto_merge, delete_branch_on_merge, security_and_analysis}'` and `gh api repos///code-scanning/default-setup --jq .state`. -## Dependabot Configuration +## Dependency Updates -Every active repo with package dependencies must have a `.github/dependabot.yml` that covers all relevant ecosystems. +Sea Haven uses the Mend Renovate GitHub App for dependency updates. Dependabot version updates are not used; do not add `.github/dependabot.yml`. Dependabot alerts stay on, and Dependabot security-update PRs are turned off once a repo is Interactive in Renovate so CVE fixes are not opened twice. + +The org-wide policy lives in the `Sea-Haven-Industries/renovate-config` repo (`org-inherited-config.json`), which Mend applies to every repo automatically. Each repo also carries a root `renovate.json` so the preset chain is visible in the repo: + +```json +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "extends": ["local>Sea-Haven-Industries/.github"] +} +``` + +Renovate detects package files on its own (`package.json`, `requirements.txt`, `.csproj`, `.tf`, workflow files). No per-ecosystem configuration is needed in the repo. Flip a repo from Silent to Interactive in the Mend Developer Portal when it should start receiving PRs. ### Pinning Principle -Exact pins are for reproducibility, not for freezing time. The pinned version is kept current by Dependabot version updates gated by CI and dependency review — never by a version number written in documentation. +Pins are for reproducibility, not for freezing time. The pinned version is kept current by Renovate PRs gated by CI and dependency review, never by a version number written in documentation. -- Never add a blanket `ignore` entry for a dependency. If a specific release is broken, ignore that release only (`versions: ["x.y.z"]`), with a comment, and remove the entry once a fixed release ships. +- npm, pip, and Terraform providers keep whatever range style the repo already uses (`rangeStrategy: bump`): a caret range is bumped to a new caret range and an exact pin is bumped to a new exact pin. The lockfile is the pin for ranged dependencies. Dependencies under an explicit exact-pin policy, such as `aws-cdk-lib` (see [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy)), stay exact. GitHub Actions are pinned to a full commit SHA with a `# vX.Y.Z` comment. +- Runtime and language versions (`node-version`, `python-version`, Terraform `required_version`, `.terraform-version`) are not bumped by Renovate. +- Never add a blanket ignore for a dependency. If a specific release is broken, add a `packageRules` entry in the repo's `renovate.json` that excludes that version only, explain why in the rule's `description` field (`renovate.json` is strict JSON and cannot carry comments), and remove it once a fixed release ships. - Never dismiss a vulnerability alert as "waiting for upstream" without a linked follow-up that advances the pin when the fix ships. -- If a bump PR fails CI, the gate worked — leave the bad release unmerged and take the next one. +- If a bump PR fails CI, the gate worked. Leave the bad release unmerged and take the next one. -### Ecosystem Selection +### Merging Renovate PRs -Choose ecosystems based on what dependency files exist in the repo: - -| File | Ecosystem | -|------|-----------| -| `package.json` | `npm` | -| `requirements.txt` | `pip` | -| `.csproj` | `nuget` | -| `.github/workflows/*.yml` | `github-actions` | - -### Standard Templates - -**Single ecosystem (npm or pip):** - -```yaml -version: 2 -updates: - - package-ecosystem: "npm" # or "pip", "nuget", "github-actions" - directory: "/" - schedule: - interval: "weekly" -``` - -**SAM project with per-function `requirements.txt`:** - -Add a separate entry for each directory containing a `requirements.txt`: - -```yaml -version: 2 -updates: - - package-ecosystem: "pip" - directory: "/src/processor" - schedule: - interval: "weekly" - - package-ecosystem: "pip" - directory: "/src/receiver" - schedule: - interval: "weekly" -``` - -**Mixed ecosystems (e.g., CDK in JS with Python Lambdas, or repos with GitHub Actions):** - -Add one entry per ecosystem/directory: - -```yaml -version: 2 -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - - package-ecosystem: "pip" - directory: "/src" - schedule: - interval: "weekly" - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" -``` - -### Merging Dependabot PRs - -- **Patch and minor bumps:** Safe to merge without review in most cases -- **Major version bumps:** Review changelog for breaking changes before merging -- When merging multiple Dependabot PRs, merge one at a time — subsequent PRs will auto-rebase +- **Minor, patch, pin, and digest updates** are grouped per ecosystem and automerge once every check on the PR passes. Renovate merges the PR itself with squash and is a bypass actor on the `main branch review` ruleset and the per-repo `main merge queue` rulesets, so no human approval is needed. Required status checks still apply. +- **Major version bumps** and **security PRs** are not automerged. Review the changelog for breaking changes, then merge by hand. +- Renovate waits three days after a release before proposing it (`minimumReleaseAge`). Security PRs skip the wait. +- Renovate PRs do not need a Jira key. ## Branch Protection @@ -155,20 +108,22 @@ Set them with `gh repo edit --add-topic a,b,c`. Adding topics is part of ## Required CI Status Check -Two org rulesets. A repo is on exactly one of them. Never both. +Two org rulesets carry the required status check. A repo is on exactly one of them. Never both. | Ruleset | Required check | Who | |---|---|---| | **main branch protection** | `ci / ci` | Unconverted remaining-lane repos | | **CI complete** | `ci-complete` | Converted HCP callers | +A third org ruleset, **main branch review**, carries the pull request rule (one approving review, squash only) for every repo except `shoc-backend`, `shoc-frontend-new`, `open-swe`, and `.github-private`. Each repo also has its own **main merge queue** ruleset. + `CI complete` starts with no repos. Flip include/unexclude in the same window as the workflow merge that lands `name: ci-complete`. Do not put portion names (`frontend / static`, `unit (1)`, `browser-smoke`) in a ruleset. If the check name in the ruleset does not match what CI actually emits, merges will be blocked by a phantom required check. Verify after any change to CI job names. Mergify YAML is not used. Converted CI keeps a `merge_group` trigger so native GitHub merge queues still run. Do not treat a missing Mergify config as a gap. Do not remove or retarget native GitHub merge-queue rulesets when flipping CI membership. -The formatter GitHub App is not on the main-branch ruleset bypass list. +The formatter GitHub App is not on the main-branch ruleset bypass list. The Renovate GitHub App is a bypass actor on `main branch review` and on each repo's `main merge queue` ruleset so it can merge its own non-major PRs; it is not a bypass actor on the required-status-check rulesets. ## Repo Hygiene diff --git a/pull-requests.md b/pull-requests.md index 94276b0..d0d9282 100644 --- a/pull-requests.md +++ b/pull-requests.md @@ -24,7 +24,7 @@ Each PR should represent a single logical change. If you find yourself writing " | `fix(auth): correct null check in session handler (PLAT-7)` | `Bug fix` | | `build: update Lambda runtime to Python 3.12 (DEV-88)` | `Updates` | -**Exemptions:** Dependabot PRs and permission-controlled emergency reverts are the only PRs that may omit the Jira key suffix. +**Exemptions:** Automated dependency-bot PRs (Renovate, and Dependabot security PRs on repos not yet Interactive in Renovate) and permission-controlled emergency reverts are the only PRs that may omit the Jira key suffix. ## Description