S19: establish landscape repository
This commit is contained in:
258
specs/refined/S5_renovate-bot-in-container
Normal file
258
specs/refined/S5_renovate-bot-in-container
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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.
|
||||
|
||||
|
||||
Affected repositories: `agiledancers`.
|
||||
Reference in New Issue
Block a user