agiledancers/specs/refined/S5_renovate-bot-in-container

# 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: <https://angular.dev/reference/versions>.
- 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/<dependency-or-group>` for eligible major updates.
- Use `renovate/minor-patch/<dependency-or-group>` 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.