Add drift check for stale OpenStack source refs

[ideaship]

Detects the silent failure that left OSISM's 2024.1 images on October 2025
sources for nine months.

Upstream renames stable/<release> to unmaintained/<release> when a release
enters the unmaintained phase, and deletes the branch at EOL.
tarballs.opendev.org keeps serving the artifact for a retired branch name but
stops regenerating it, so a build that still asks for
<project>-stable-<release>.tar.gz keeps succeeding while its sources sit
frozen at the moment of the rename. Nothing fails, so nothing prompts a fix —
which is exactly what happened to 2024.1, and only surfaced when a fix for
CVE-2026-55707 failed to appear in a freshly rebuilt image.

• https://osism.tech/docs/appendix/security/ossa-2026-032/
• https://bugs.launchpad.net/neutron/+bug/2152113

That instance is fixed (#2640, osism/container-images-kolla#762).
This adds the check that would have caught it on day one, and will catch 2025.1
when it transitions.

The three commits

Please rebase-merge rather than squash: the first commit is an independent
fix to pre-existing code and the third a general driver capability, and both
read better in main's history on their own.

1. http: scope rate-limit hints to the host — a pre-existing bug, fixable
   and reviewable on its own. _rate_limit_hint() describes GitHub's rate
   limits but never checked that the response came from GitHub, so any
   markerless 429 was reported as raw.githubusercontent.com CDN throttling
   with advice built around that host. Reachable today through a non-GitHub
   github_raw/github_api override — the same case _auth_headers() already
   guards a token against. Behaviour for GitHub hosts is unchanged.
2. Add drift check for stale OpenStack source refs — the plugin, plus the
   transport and parsing it needs.
3. Refuse a local-only run that needs the network — --base-dir without
   --remote-fallback is a local-only run, and source._resolve() enforces it
   by erroring rather than fetching. This plugin asks what upstream publishes
   right now, which no checkout records, so it would reach the network
   regardless of the mode requested. A plugin may now declare EXTERNAL_HOSTS
   and the driver refuses such a run up front, listing every offending plugin at
   once. Optional and read with getattr, so no other plugin changes.

Design notes worth a look

Artifact-driven, not branch-driven. The question is which tarball the build
consumes, so probing the published set answers it directly. It also avoids a
blocker: release_to_ref would need an upstream owner configured per project,
and sources maps only kolla and kolla_ansible (default owner osism), so
a branch probe would 404 on all 21 projects.

Only two phases are probed, because only two are published. Upstream marks
both transitions with a tag — <release>-eom when the stable branch becomes
unmaintained, <release>-eol when the unmaintained branch is deleted — and
those tags invite the assumption that they are further phases to move to. They
are not: opendev builds an artifact per branch, so no tarball exists for
either tag. Verified 404 for every <release>-eol and <release>-eom URL
checked across nova, aodh, keystone, cinder, glance and requirements, over
2023.1, 2023.2, 2024.1, 2024.2, victoria, wallaby and zed — while a release-tag
tarball such as nova-30.0.0.tar.gz does resolve. The tags also run the
opposite way round from what the names suggest: nova carries 2024.1-eom and
2023.1-eom while unmaintained/2024.1 and unmaintained/2023.1 are still
live branches, and 2023.2-eol/2024.2-eol sit on series whose branch is
already deleted. A full run is 68 probes, and a release already moved to
unmaintained costs none.

One HEAD per candidate, not the index listing. My first version read the
per-project index — fewer requests, one per project covers all releases — but
those listings are large (nova's is ~1.4 MB with 10k entries) and timed out
intermittently in live runs, first on keystone at 30s then nova at 90s. A HEAD
is a few hundred bytes.

An unanswered probe is unknown, not clean. Reading an outage or a throttled
response as "no later phase published" would report no drift and silently
reinstate the blind spot this check exists to close, so anything but a 200 or a
404 raises ProbeInconclusive. That guard sits on the finding, not on the
run: the driver wraps its whole plugin loop in one handler, so raising would
discard every other plugin's findings over one upstream hiccup. scan() catches
it per project and reports the ref as unverified — phase unknown rather than
confirmed current, in its own report block, actionable so the run still exits
non-zero. head() additionally retries a transport failure or a transient
status once with a backoff; measured first, 110 sequential HEADs against opendev
took 47s with no 429 and no 5xx and no rate-limit headers in the responses
(plain Apache, no CDN), so a blip is the failure mode there rather than
throttling.

Silence is not always a clean bill of health. For a release with no later
phase published — 2024.2, which is EOL — the frozen stable tarball is the only
option and nothing is flagged. That is correct behaviour, but it means silence
there says "no better ref exists", not "sources are current".

Verification

Replayed against the pre-fix manifest with live probes: 21 of 22 refs flagged
in 9s, gnocchi correctly skipped because stable/4.6 does not follow the
release lifecycle. Against the current tree the plugin reports nothing, and
2024.2 and 2025.x stay silent. A local-only run exits 2 before any probe; a full
live run takes 30s.

Each commit was checked out into a clean worktree and verified there — 341,
392 and 398 tests passing respectively, flake8 and black clean at every
step.

Not covered

The requirements ref in container-images-kolla scripts/002-generate.sh is
hardcoded rather than read from the manifest, so this plugin cannot see it.
Detecting that would mean parsing shell in another repo. The retirement guide's
checklist is the control there:

• Document the unmaintained-phase ref switch osism.github.io#1048

Two related refs are also outside what this checks, both currently still on
stable-: openstackclient/Containerfile in container-images (a no-op today —
that matrix builds only 2025.1/2025.2/2026.1) and the IPA artifacts in
container-image-kolla-ansible, where ipa-centos9-unmaintained-2024.1.initramfs
exists and is fresh while the stable-2024.1 one froze on 2025-10-09.