# 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:

1. Prefer mirrored images first, then fallback upstream sources when mirror resolution fails.
2. Use digest-aware freshness checks when deciding whether local image cache is current.
3. Pin registry auth realm hosts when `WWW-Authenticate` challenge host differs from registry host.
4. Use bounded login/pull/push retry wrappers in image publication and consumption lanes.
5. Propagate and verify immutable digest references for downstream runtime validation lanes.
6. 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

1. Keep per-job ad hoc retries only.

- Rejected due to repeated regressions and inconsistent behavior.

2. Depend solely on upstream registries.

- Rejected due to local network and availability constraints.

3. 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.md`
- `ADR003-deployable_runtime_image_contract.md`