ff51f04c36
Some checks failed
CICD / Build and Publish CICD Base Image (pull_request) Successful in 16s
CICD / Build and Push CICD Image (pull_request) Successful in 15m46s
CICD / Build CICD Image Failure Postmortem (pull_request) Has been skipped
CICD / Frontend Dependency Audit (pull_request) Failing after 1m54s
CICD / Backend Dependency Audit (pull_request) Failing after 1m7s
CICD / Source Checks (pull_request) Has been cancelled
CICD / CICD Tests Complete (pull_request) Has been cancelled
CICD / Build Backend Base Image (pull_request) Has been cancelled
CICD / Build Frontend Base Image (pull_request) Has been cancelled
CICD / Build Integration Tester Image (pull_request) Has been cancelled
CICD / Runtime Black-Box Integration Tests (pull_request) Has been cancelled
CICD / Build E2E Tester Image (pull_request) Has been cancelled
CICD / Build Backend Main Image (pull_request) Has been cancelled
CICD / Build Frontend Main Image (pull_request) Has been cancelled
CICD / End-to-End Tests (pull_request) Has been cancelled
CICD / Production Images Complete (pull_request) Has been cancelled
CICD / Production Image Failures Postmortem (pull_request) Has been cancelled
CICD / Source Lanes Failure Postmortem (pull_request) Has been cancelled
CICD / Integration Tests Failure Postmortem (pull_request) Has been cancelled
CICD / E2E Tests Failure Postmortem (pull_request) Has been cancelled
2.5 KiB
2.5 KiB
ADR004: Registry Image Resolution and Auth Resilience Policy
- Status: Accepted
- Date: 2026-07-16
Context
The CI and Renovate workflows run on self-hosted runners with intermittent DNS and network instability. Recent failures showed that image pull/push reliability depends on more than simple retries:
- registry token realms may resolve to a different host than the registry endpoint
- mirror images can become stale relative to upstream
- downstream lanes require immutable references from upstream lanes
- Renovate must operate across internal/external endpoint paths with token variability
Without an explicit policy, each job implements ad hoc behavior and drift reintroduces flakiness.
Decision
Adopt a cross-workflow reliability policy for registry/image operations:
- Prefer mirrored images first, then fallback upstream sources when mirror resolution fails.
- Use digest-aware freshness checks when deciding whether local image cache is current.
- Pin registry auth realm hosts when
WWW-Authenticatechallenge host differs from registry host. - Use bounded login/pull/push retry wrappers in image publication and consumption lanes.
- Propagate and verify immutable digest references for downstream runtime validation lanes.
- Keep retry counts/timeouts configurable as operational tuning, not architectural invariants.
Scope
This ADR applies to:
.gitea/workflows/cicd.yaml.gitea/workflows/renovate.yml- helper scripts used for mirrored image resolution and lane orchestration
This ADR does not prescribe exact retry constants or runner sizing thresholds.
Consequences
Positive:
- reduced CI flakiness from token realm host mismatch and transient registry failures
- stronger traceability via digest-first downstream checks
- clearer operator expectations for endpoint/token/image fallback behavior
- consistent reliability approach across CICD and Renovate workflows
Negative:
- increased workflow script complexity and duplicated helper logic inside isolated step shells
- additional maintenance burden to keep helper patterns consistent across lanes
Alternatives Considered
- Keep per-job ad hoc retries only.
- Rejected due to repeated regressions and inconsistent behavior.
- Depend solely on upstream registries.
- Rejected due to local network and availability constraints.
- Rebuild missing artifacts in downstream lanes.
- Rejected because it breaks publish-once/consume-many behavior and weakens traceability.
Related Decisions
ADR002-cicd_base_image_tagging.mdADR003-deployable_runtime_image_contract.md