Daily workflow

Dependencies: an agent you configure once and supervise forever.

Every real project sits on top of packages other people update weekly. Left alone, those updates pile up into risky, months-long upgrade projects. Handled well, they arrive as a steady stream of small pull requests opened by a bot, tested by your CI, and merged under your review. That bot is a dependency-update agent, and directing it uses the exact skills this whole site teaches: write the rules down, let machinery do the repetitive work, verify before trusting.

#The mental model

Your project declares intent (roughly which versions it wants, in package.json or similar) and records resolution (exactly which versions it got, in a lockfile). A dependency bot watches the package registries, notices when something newer satisfies your intent, and opens a pull request that updates both files together. Your CI runs on that PR like on any other. You review and merge, or you teach the bot which categories it may merge itself.

The tool used across these repos is Renovate. Treat it exactly like the coding agents on the AI agents & rules page: it is tireless and consistent, it does exactly what its instructions say, and it has no judgment about what its changes mean. The instructions file is the contract; the PRs and dashboard are how you supervise.

#What the bot actually does to a repo

Concretely, on this repo (Groundwork) and its siblings, Renovate:

• Opens eligible grouped PRs on the daily run, labeled dependencies. Related bumps travel together so review is one read, not twenty.
• Maintains an always-current Dependency Dashboard issue: every pending update, what is held by the maturity floor or rate limits, and what requires approval. Ticking an approval checkbox releases that held update for a future run.
• Opens security PRs on the next daily runner pass, explicitly bypassing the routine schedule, age floor, and rate limits. Renovate does not merge them: a human reviews and merges each PR after its required CI succeeds.
• Updates things that are not npm packages at all: GitHub Actions pinned to commit SHAs (it moves the pin and the human-readable version comment together) and Docker base-image digests.
• Embeds each package's release notes in the PR body, so the review starts with what changed, not with hunting for a changelog.

#The cooldown: patience as a security control

Supply-chain attacks on package registries follow a pattern: a malicious release appears (a hijacked maintainer account, a typosquat, a compromised build), and the ecosystem usually catches and yanks it within days. A cooldown (Renovate's minimumReleaseAge) says: do not propose a supported timestamped release younger than N days. These repos use five days for supported normal timestamped major, minor, and patch updates. You give up a little freshness and buy a real defense: by the time a supported version reaches a PR, the world has had time to notice if it was poisoned.

Package managers are adopting the same idea at install time (pnpm's minimumReleaseAge refuses too-young versions during resolution), so the floor holds even when a human runs the install by hand. Security fixes get an explicit escape hatch, because for a known vulnerability the risk calculus reverses.

#One policy, many repos

Once two repos both run the bot, their configs drift: one repo gets a better cooldown, the other keeps the old value, and nobody decided that. The fix is the same one you use for agent rules: define shared policy once, in one place, and have each repo reference it. Renovate supports this with shareable presets. These repos extend a small public preset repo, renovate-config, which holds only the policy that must stay identical everywhere: schedule, cooldown, PR limits, labels, rebase behavior, and the security-PR rules. Anything repo-specific (which packages need human review, which groups make sense) stays in that repo's own renovate.json.

#Hosted or self-hosted: a real choice

Renovate runs two ways, and both are legitimate:

• The hosted Mend app: two clicks to install, zero credentials to manage. Right for a first project and for anyone who never wants to read a job log. One trap: in the onboarding wizard the default mode can be "Scan Only," which runs silently and opens nothing. Pick "Scan and Alert" (Interactive), or the bot looks installed but broken.
• A self-hosted runner: a small GitHub Actions workflow in an automation repo that runs Renovate on a schedule with a token you control. You gain what hosted hides: every run is a log you can open, grep, and re-dispatch with debug logging. These repos moved to self-hosted after three separate "why is the bot ignoring me?" mysteries whose answers all lived in logs only the hosted portal could see.

The trade is the same one this site keeps pointing at: convenience versus observability. Start hosted if you're new; move to self-hosted the first time you can't answer "what is the bot doing?" from where you sit. The config file is identical either way, so switching is an executor swap, not a migration.

These repositories run the self-hosted process daily. Every run evaluates eligible routine updates after their maturity floor and notices vulnerable updates promptly; there is no second weekly branch-creation window. A slower executor clock would delay both ordinary maintenance and urgent fixes after their other controls have cleared.

#Supervising the bot

The human stays the senior partner. In practice that means the config encodes different trust levels for different blast radii:

• High-blast-radius majors are held for approval. Groundwork treats an Ubuntu base-image major as a platform migration, so it appears on the dashboard for approval instead of opening a routine PR. A major upgrade with that compatibility impact is deliberate work with its own plan.
• High-blast-radius packages always get human review, even for patches. Deployment engines and infrastructure adapters can break everything at once; the config forbids automerging them.
• Automerge is earned, not default. This policy leaves security and routine dependency PRs for human review and merge after required CI. Any future automerge category would need its own evidence and an explicit policy decision.
• The dashboard is the console. When something seems stuck, the answer is almost always there: held by maturity or rate limits, awaiting approval, or blocked by a config error the bot is reporting.

#Set it up on your own project

The five-minute version, for a project on GitHub:

1. Install the Mend Renovate app on your repo (choose Renovate Only, mode Interactive).
2. Merge the onboarding PR it opens, or commit a minimal renovate.json yourself:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:best-practices", "schedule:weekly"],
  "minimumReleaseAge": "5 days",
  "internalChecksFilter": "strict",
  "packageRules": [{
    "matchDatasources": ["npm"],
    "matchUpdateTypes": ["major", "minor", "patch"],
    "minimumReleaseAge": "5 days",
    "internalChecksFilter": "strict"
  }],
  "labels": ["dependencies"],
  "vulnerabilityAlerts": {
    "enabled": true,
    "schedule": ["at any time"],
    "minimumReleaseAge": null,
    "prHourlyLimit": 0,
    "prConcurrentLimit": 0,
    "prCreation": "immediate",
    "automerge": false,
    "platformAutomerge": false
  }
}

3. Make sure CI runs on pull requests, so bot PRs get the same verification as yours. If there is no CI yet, that is the first thing to fix; a dependency bot without tests is just automated risk.
4. Watch the Dependency Dashboard issue it opens, and read your first few PRs end to end, release notes included.

#Practice

• Open the Dependency Dashboard issue on a repo that has one. For each pending update, say out loud why it hasn't merged yet: schedule, cooldown, or awaiting review.
• Read one Renovate PR top to bottom, including the embedded release notes. Find one changed thing that could matter to the code, even if the answer is "nothing here affects us."
• Tick a dashboard checkbox to force a PR ahead of schedule, watch CI run on it, and merge it yourself.
• In any project, run your package manager's outdated command (pnpm outdated, npm outdated) and compare what it shows against what the bot has proposed. If they differ, work out which policy (cooldown, grouping, held majors) explains the gap.

#Going deeper

• Renovate's upgrade best practices: the maintainers' own advice on cadence, grouping, and automerge.
• The Dependency Dashboard: everything the checkboxes can do.
• renovate-config: this owner's shared preset and self-hosted runner, documented as a copyable reference, including the token permissions that tripped us and the incidents that drove the self-hosted move.
• Renovate configuration options: the full vocabulary once you outgrow the starter config.