# S5 — Renovate bot in a container Status: REFINED Agreed after the grill-me review; shared understanding confirmed. ## User story As a developer, I want a containerized Renovate bot to check the repositories on our Gitea server and propose dependency updates through pull requests, so that frontend, backend and build infrastructure dependencies remain maintainable and we reduce risks from outdated versions. I want external release age and project compatibility to constrain those proposals. I retain control over merging and can upgrade dependencies manually when I deliberately choose to act outside the bot's waiting period. ## Environment and scope - Gitea and its container registry run on the existing Synology. Renovate runs in a container on that same Synology; no additional hardware is required. - The established Synology target platform is `linux/amd64`. - Discover all repositories on this Gitea instance for which the dedicated bot account has the necessary access. Support explicit repository exclusions. - Before dependency PRs are proposed for a newly discovered repository, create an onboarding/configuration PR. A maintainer must approve and merge that configuration first. - This project contains a `renovate.json` with its agreed compatibility and update boundaries. Other onboarded repositories have their own reviewed configuration. - Use a dedicated bot account/token with the access required for repository discovery, branches, PRs, dashboards and dependency metadata lookup. Keep credential values outside Git and logs. ### Dependency surfaces Cover supported maintained dependency declarations, including: - Frontend dependencies and development dependencies, compilers and test tools. - Backend dependencies, Maven parents/BOMs, plugins and version properties. - Docker base images and maintained container-image references. - Pinned workflow actions, including version/digest references. - The Renovate container's own version declaration. - Related lockfile changes and separate lockfile maintenance. Detection must include relevant maintained references outside ordinary manifests, for example the Playwright image reference in the Java CI helper. Where related references must match, update and validate them together. The Playwright package and browser image must stay aligned. One explicit manual boundary remains: the runner binary download version and its binary SHA-256 checksum in the CI setup helper are maintained manually. Document this boundary. Do not generate a partial runner update, leave an obsolete checksum, or confuse a Git commit SHA with the binary's SHA-256. Unsupported dependency references or missing required metadata must be visible as limitations/blockers, rather than silently counted as successfully managed. ## Schedule and execution - Run daily at **06:00 in `Europe/Amsterdam`**. The schedule/timezone are configurable and the default is recorded in the deployment configuration. - Provide the actual scheduler/container setup on the Synology; adding an image declaration alone does not make the periodic execution operational. - The Synology can perform dependency checks while the development mini-PC is off. Project CI jobs still depend on their existing runner availability. - The daily run can discover candidates, maintain eligible PRs and propose new eligible updates within the agreed limits. It does not merge updates. ## Seven-day release-age policy ### Universal bot policy - A release must be at least **seven days old** before Renovate proposes that version in a dependency PR. - Apply this to all bot-proposed dependency updates, including internal libraries, security updates, infrastructure dependencies and the bot's own image update. There is no internal-library or security-update exception. - Apply the same check when an existing PR is updated to a newer version. An existing eligible PR must not gain an ineligible new version through refresh. - Missing or unreliable release timestamps block the affected proposal until its age is demonstrable. Do not treat missing metadata as proof of sufficient age. - Show the concrete blocker in the repository dashboard, with useful diagnostics. A dependent/coherent update group cannot be partially proposed in an invalid combination to work around an age blocker. - Enforce the policy centrally across onboarded repositories. Repository-local configuration, security-update defaults or bot retry/approval mechanisms must not silently relax the waiting period or timestamp requirement. - A maintainer may choose to upgrade earlier **manually**, outside Renovate. That does not authorize Renovate to bypass its policy. ### Lockfiles and transitives The waiting period also applies to newly introduced or changed transitive versions in bot-generated lockfile changes. Determine those changes relative to the repository base revision used by the proposal. - Validate the age of those versions before the PR is created or updated. - Unknown ages block the affected proposal, just as they do for direct updates. - Existing unchanged versions in the base revision are not newly introduced by the bot; the policy is not a requirement to rewrite all historical lock entries. - Additional validation is part of S5 where Renovate's native behavior cannot establish this guarantee. Do not assume a package-manager cutoff covers every fallback path. - A failing validator must actually prevent PR creation/update. A command that fails but only adds an artifact error or failed status to an already-created ineligible PR does not satisfy this requirement. ### Metadata limitations Not every datasource/registry supplies usable release timestamps. This includes some container-image sources. Such updates remain blocked and visible unless reliable metadata support is implemented and validated; manual maintenance is possible outside the bot. For example, the npm release timestamp of Playwright is not proof of the release age of its separately published container image. Both references must satisfy applicable policy before their coordinated bot proposal is offered. ## Compatibility and upgrade boundaries ### Project-owned boundaries - The official Angular compatibility table is the reference for Angular's Node.js, TypeScript and RxJS compatibility: . - Project maintainers encode and maintain the applicable ranges in `renovate.json`, including supported Node majors and TypeScript minor ranges. - Renovate must stay within those explicit ranges and must not independently widen the policy to make a proposed version eligible. - Boundaries must reflect the actual installed framework/tooling metadata where relevant. Remaining in the same dependency major is not sufficient if Angular requires a narrower range. - Node.js, TypeScript and RxJS updates, including major updates, may be proposed when the explicit project boundaries allow them and they remain compatible with the project's Angular version. ### Angular upgrades - Angular major upgrades are performed manually through a separate specification. - Libraries/tooling whose major numbering follows Angular are upgraded to a new major with Angular, also through that manual specification. - Renovate proposes only minor and patch updates for Angular and that aligned family, maintaining a coherent compatible combination. - Runtime/compiler dependencies that require matching versions stay aligned. Do not assume unrelated Angular tooling repositories must all have identical patch numbers merely because their majors align. - Group related changes where necessary to preserve compatibility. TypeScript and RxJS proposals still obey their own explicit allowed ranges. ### Declared versions versus installed software Maintain coherent repository declarations where a dependency appears in multiple places, such as Node requirements in manifests, version files, Docker definitions and setup checks. A bot PR does not install a new Node version on the mini-PC or replace a running container. Those are documented manual management actions. ## Branches, PRs and limits - Use the branch prefix `renovate/`. - Use `renovate/major/` for eligible major updates. - Use `renovate/minor-patch/` for eligible minor/patch updates. - Each independent dependency has its own update PR. Related packages from one upstream project may be grouped to maintain a coherent update. - Keep major-update proposals separate from minor/patch proposals. Necessary companion changes belong with the coherent upgrade they support; unrelated smaller updates are not mixed into a major PR. - Maintain at most **five open dependency PRs per repository**, including the separate lockfile-maintenance PR when one exists. - Queue additional eligible updates for a later daily round after slots become available. There is no dynamic sixth/seventh overflow PR or custom overflow bundling requirement. - Onboarding/configuration PRs are outside this dependency-PR limit and precede ordinary dependency proposals. - Renovate creates and updates proposals only. Maintainers review the change and CI result and merge manually; automerge is disabled. ## Lockfile maintenance - Ordinary manifest updates include the matching lockfile changes in the same PR, so reproducible installation remains valid. - Separately maintain lockfiles within the existing manifest boundaries on a branch such as `renovate/minor-patch/lockfile-maintenance`. - Keep that maintenance PR separate from ordinary dependency-update PRs and count it within the five-PR limit. - Apply the same seven-day checks to newly resolved/changed versions in that PR. - Do not split a normal manifest update from the lockfile required by that update into separately mergeable, inconsistent proposals. ## Maintaining existing PRs During daily execution, Renovate may refresh existing bot proposals and rebase them when the base branch changes. Refreshed candidates must again pass age and compatibility checks. Do not overwrite manual changes on bot branches. If manual edits or conflicts prevent safe maintenance, preserve those edits and show that maintainer action is required in the dashboard. ## Visibility and management - Provide a Dependency Dashboard issue per onboarded repository for pending, open and blocked updates and relevant failures. - Explain age, missing metadata and compatibility blockers concretely. - Preserve execution logs and the result of each scheduled run for **thirty days**, with rotation/retention configured and secret values omitted/redacted. - Retain operational failure information on the Synology even if startup or Gitea connectivity fails before repository processing can update a dashboard. - Provide a management guide covering bot access and secret locations, repository discovery/exclusions and onboarding, schedule/timezone, manual execution, dashboards/logs, configuration validation and recovery. - Document project compatibility maintenance, the manual runner version/checksum boundary, blocked unsupported metadata, manual host/runtime updates and applying an approved Renovate-image version to the running installation. ## Acceptance criteria - [ ] A working Renovate container and daily 06:00 Europe/Amsterdam schedule run on the existing linux/amd64 Synology. - [ ] Discovery covers authorized Gitea repositories, respects exclusions and requires onboarding/configuration approval before dependency proposals. - [ ] This project has a reviewed `renovate.json` with explicit framework and dependency boundaries; compatible managed dependency surfaces are detected. - [ ] Direct, security and new/changed transitive lockfile versions younger than seven days cannot enter new or refreshed bot PRs. - [ ] Unknown release ages block proposals visibly; internal dependencies do not bypass the waiting period. - [ ] Validation proves repository overrides, security defaults and error/fallback paths cannot create or update an ineligible PR. - [ ] Node.js, TypeScript and RxJS updates stay inside the maintainer-controlled Angular compatibility bounds, including any permitted major upgrades. - [ ] Angular and Angular-major-aligned library major upgrades are not proposed; compatible minor/patch changes and coupled package/image references remain coherent. - [ ] Independent proposals and permitted coherent groups use the agreed renovate/major/... and renovate/minor-patch/... branch conventions. - [ ] Major proposals remain separate from unrelated minor/patch updates. - [ ] No more than five dependency PRs are open per repository, including lockfile maintenance; remaining candidates wait rather than form overflow PRs. - [ ] Normal manifest PRs include matching lockfiles; separate lockfile maintenance stays within manifest ranges and satisfies the same age policy. - [ ] Daily maintenance preserves manual branch edits and reports conflicts; merging and actual host/container upgrades remain manual. - [ ] The runner binary version/checksum is explicitly documented as manual, with no partial or incorrect automated checksum updates. - [ ] Dashboards expose repository-level state; thirty-day logs also expose failures before repository processing without disclosing secrets. - [ ] Management documentation and real execution/PR evidence demonstrate the operational setup and enforcement. Configuration files alone are insufficient. ## Implementation handoff This specification records agreed behavior. It does not create the bot account, configure credentials, deploy a container, install a schedule or create PRs/issues. Those actions, any necessary additional age validation and the operational evidence are implementation work. S5 is complete only when its behavior has been proven on the working installation.