imbi-plugin-github 2.28.0__tar.gz → 2.29.0__tar.gz

{imbi_plugin_github-2.28.0 → imbi_plugin_github-2.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imbi-plugin-github
-Version: 2.28.0
+Version: 2.29.0
 Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
 Author-email: "Gavin M. Roy" <gavinr@aweber.com>
 License-Expression: BSD-3-Clause
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
 Requires-Dist: httpx>=0.27
-Requires-Dist: imbi-common[databases]==2.28.0
+Requires-Dist: imbi-common[databases]==2.29.0
 Requires-Dist: pydantic>=2
 Requires-Dist: pyjwt[crypto]>=2.8
 Description-Content-Type: text/markdown

{imbi_plugin_github-2.28.0 → imbi_plugin_github-2.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "2.28.0"
+version = "2.29.0"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -18,7 +18,7 @@ classifiers = [
 ]
 dependencies = [
   "httpx>=0.27",
-  "imbi-common[databases]==2.28.0",
+  "imbi-common[databases]==2.29.0",
   "pydantic>=2",
   "pyjwt[crypto]>=2.8",
 ]

{imbi_plugin_github-2.28.0 → imbi_plugin_github-2.29.0}/src/imbi/plugins/github/deployment.py

@@ -53,6 +53,7 @@ from imbi.common.plugins.base import (
     DeploymentCapability,
     DeploymentEventStatus,
     DeploymentRun,
+    EnvironmentDeploymentState,
     LinkWriteback,
     NotesListing,
     PluginContext,
@@ -152,6 +153,21 @@ _NOTE_BLOB_CONCURRENCY = 10
 _FULL_SHA_PATTERN = re.compile(r'^[0-9a-f]{40}$')
 
 
+class _StatusRead(typing.NamedTuple):
+    """One deployment's status history, as far as it could be read."""
+
+    status: DeploymentEventStatus
+    log_url: str | None
+    #: The newest entry is GitHub's ``inactive`` notice, so this
+    #: deployment has been retired whatever ``status`` says it did.
+    superseded: bool
+    #: Nothing was read -- ``status`` is the ``pending`` fallback rather
+    #: than an observation.  Resync wants that fallback (a noisy row must
+    #: not fail a whole project); anything deciding what an environment
+    #: serves has to know the difference.
+    unreadable: bool
+
+
 def _note_sha(path: object) -> str | None:
     """Annotated commit SHA for a notes-tree path, or ``None``.
 
@@ -435,6 +451,43 @@ def _mainline_branches(
     return configured or _DEFAULT_MAINLINE_BRANCHES
 
 
+# How many deployments per environment ``get_environment_state`` walks
+# before it stops looking for the active one.  GitHub returns
+# deployments newest-first, and the active deployment is normally the
+# first or second row; a deeper walk only pays off on an environment
+# whose recent history is a run of failures.  Each row costs one status
+# request, so the cap bounds the request count per environment rather
+# than the wall time of one call.
+_DEFAULT_ACTIVE_SCAN_LIMIT = 10
+# One page holds the whole scan -- GitHub caps ``per_page`` at 100.
+_MAX_ACTIVE_SCAN_LIMIT = 100
+
+
+def _active_scan_limit(
+    integration_options: dict[str, typing.Any],
+) -> int:
+    """Resolve the ``active_scan_limit`` integration option.
+
+    Declared integration-level beside ``mainline_branches`` because how
+    deep the scan has to go is a property of the org's deploy habits, not
+    of one capability.  Operator-entered values arrive as strings from the
+    admin form as often as integers, so both are accepted; anything absent,
+    unparseable, or below 1 resolves to
+    :data:`_DEFAULT_ACTIVE_SCAN_LIMIT`, and the value is clamped to what a
+    single GitHub page can carry.
+    """
+    raw = integration_options.get('active_scan_limit')
+    if isinstance(raw, bool) or not isinstance(raw, (int, str)):
+        return _DEFAULT_ACTIVE_SCAN_LIMIT
+    try:
+        limit = int(raw)
+    except ValueError:
+        return _DEFAULT_ACTIVE_SCAN_LIMIT
+    if limit < 1:
+        return _DEFAULT_ACTIVE_SCAN_LIMIT
+    return min(limit, _MAX_ACTIVE_SCAN_LIMIT)
+
+
 def _commit_from_payload(payload: dict[str, typing.Any]) -> Commit:
     """Convert a GitHub commit list/object payload into a :class:`Commit`."""
     sha = str(payload.get('sha', ''))
@@ -912,23 +965,26 @@ class GitHubDeployment(DeploymentCapability):
         ctx: PluginContext,
         credentials: dict[str, str],
         namespace: str,
+        skip_shas: collections.abc.Collection[str] = (),
     ) -> NotesListing:
         """Every note on ``refs/notes/<namespace>`` at its current tip.
 
         Two Git Data calls to reach the tree, then one blob read per
-        note.  A missing ref answers an empty, complete listing.
+        note the caller did not ask us to skip.  A missing ref answers
+        an empty, complete listing.
 
         ``complete`` compares what the tree holds against what came
         back: :meth:`_all_notes` drops a note whose blob it cannot read
         (logging why), and a truncated tree listing hides notes before
         that.  Either way the caller must not treat the result as the
-        whole ref.
+        whole ref.  A note skipped on request does not make the listing
+        incomplete -- the caller already has that answer.
         """
         async with self._client(ctx, credentials) as client:
             tip = await self._notes_ref_tip(client, namespace)
             if tip is None:
                 return NotesListing({}, True)
-            return await self._all_notes(client, tip)
+            return await self._all_notes(client, tip, skip_shas)
 
     async def diff_commit_notes(
         self,
@@ -1080,17 +1136,22 @@ class GitHubDeployment(DeploymentCapability):
         return out, not truncated
 
     async def _all_notes(
-        self, client: httpx.AsyncClient, commit_sha: str
+        self,
+        client: httpx.AsyncClient,
+        commit_sha: str,
+        skip_shas: collections.abc.Collection[str] = (),
     ) -> NotesListing:
         """Every note at one notes-ref commit, bodies included.
 
         Blob reads run a few at a time (one request per note) and an
         unreadable note is skipped rather than failing the batch or
-        recording a false "removed".
+        recording a false "removed".  A note whose annotated commit is
+        in ``skip_shas`` costs no request at all.
 
         ``complete`` combines the two ways this can fall short: a
         truncated tree listing, and a blob that would not read.  Either
-        means the map is not the whole ref.
+        means the map is not the whole ref.  Notes skipped on request do
+        not count against it.
         """
         notes, tree_complete = await self._tree_notes(client, commit_sha)
         gate = asyncio.Semaphore(_NOTE_BLOB_CONCURRENCY)
@@ -1102,7 +1163,12 @@ class GitHubDeployment(DeploymentCapability):
                 except httpx.HTTPError as exc:
                     return exc
 
-        items = list(notes.items())
+        skip = {sha.lower() for sha in skip_shas}
+        items = [
+            (annotated, blob_sha)
+            for annotated, blob_sha in notes.items()
+            if annotated.lower() not in skip
+        ]
         bodies = await asyncio.gather(
             *(_read(blob_sha) for _, blob_sha in items)
         )
@@ -1120,7 +1186,7 @@ class GitHubDeployment(DeploymentCapability):
                 # a ``None`` here would read as "note removed".
                 continue
             out[annotated] = body
-        return NotesListing(out, tree_complete and len(out) == len(notes))
+        return NotesListing(out, tree_complete and len(out) == len(items))
 
     @staticmethod
     async def _blob_text(
@@ -1631,6 +1697,235 @@ class GitHubDeployment(DeploymentCapability):
             )
         return [observed for group in per_env for observed in group]
 
+    async def get_environment_state(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        environments: list[str],
+    ) -> list[EnvironmentDeploymentState]:
+        """Report the active deployment per environment.
+
+        Fans out one ``GET /deployments?environment={env}`` call per
+        environment (newest-first, as GitHub orders them) and walks the
+        page fetching each deployment's statuses until one both maps to
+        exactly ``success`` -- not ``pending``, not ``in_progress`` -- and
+        carries no ``inactive`` notice on top.  That deployment is the
+        active one.
+
+        Policy note: GitHub can leave several deployments active at once
+        when automatic inactivation is disabled, so "active" cannot be
+        read off the provider's own flag.  Imbi's policy is *active = the
+        newest deployment whose latest provider status is success*, which
+        is well-defined either way.
+
+        The walk is bounded by the ``active_scan_limit`` option (see
+        :func:`_active_scan_limit`).  Reaching the cap without a success
+        resolves ``unknown``, never ``none``: an older active deployment
+        may sit just past the cap, and reporting ``none`` would have the
+        host clear a pointer that is right.
+
+        Two degraded reads resolve ``error`` for the same reason.  A row
+        whose status history would not read (``status_unknown``), or one
+        too malformed to identify at all, leaves the walk unable to say
+        what that deployment did -- throttling blinds every row at once
+        -- and a 404 on the listing itself means the repo moved or the
+        token lost access, not that the environment is empty.  An *empty*
+        listing resolves ``unknown``: GitHub says ``[]`` both for an
+        environment never deployed to and for a name it does not
+        recognise, and local slugs reach it unmapped.
+
+        An unreadable row outranks a success found *below* it, so it wins
+        over ``found`` rather than being noted alongside it.  The walk
+        stops at the first clean success, which means every row it could
+        not read is newer than that success and may be the deployment
+        actually serving the environment; calling the older one active
+        would have the host write a stale pointer.
+
+        So ``none`` requires positive evidence -- rows read, none of them
+        serving.  Everything else the host must read as "keep what you
+        have".
+        """
+        scan_limit = _active_scan_limit(ctx.integration_options)
+        # Same memoisation as the resync sweep: one triggering-actor
+        # lookup per run and one release lookup per ref, shared across the
+        # parallel per-env fan-out.
+        run_cache: dict[str, tuple[str, str] | None] = {}
+        release_lookups: dict[str, asyncio.Task[RemoteRelease | None]] = {}
+        mainline = _mainline_branches(ctx.integration_options)
+        async with self._client(ctx, credentials) as client:
+            return list(
+                await asyncio.gather(
+                    *(
+                        self._environment_state(
+                            client,
+                            env,
+                            scan_limit,
+                            run_cache,
+                            release_lookups,
+                            mainline,
+                        )
+                        for env in environments
+                    )
+                )
+            )
+
+    async def _environment_state(
+        self,
+        client: httpx.AsyncClient,
+        environment: str,
+        scan_limit: int,
+        run_cache: dict[str, tuple[str, str] | None],
+        release_lookups: dict[str, asyncio.Task[RemoteRelease | None]],
+        mainline: frozenset[str],
+    ) -> EnvironmentDeploymentState:
+        """Resolve one environment's active deployment."""
+        try:
+            resp = await client.get(
+                '/deployments',
+                params={
+                    'environment': environment,
+                    'per_page': str(scan_limit),
+                },
+            )
+            if resp.status_code == 404:
+                # NOT ``none``, though the listing path treats a 404 as
+                # "nothing to import".  Here ``none`` authorizes the host
+                # to clear the environment's current-release pointer, and
+                # GitHub answers 404 for a repo that was renamed or
+                # transferred, or one this installation lost access to --
+                # the very conditions link writeback exists to self-heal.
+                # An unknown *environment* is a 200 with an empty list, so
+                # nothing legitimate is lost by refusing to read a 404 as
+                # an answer.
+                LOGGER.warning(
+                    'Active deployment scan got 404 for env=%s; treating '
+                    'it as unreadable rather than as "nothing deployed"',
+                    environment,
+                )
+                return EnvironmentDeploymentState(
+                    environment=environment, active_resolution='error'
+                )
+            resp.raise_for_status()
+            deployments = typing.cast(list[dict[str, typing.Any]], resp.json())
+        except (httpx.HTTPError, ValueError):
+            LOGGER.warning(
+                'Failed to resolve active deployment for env=%s',
+                environment,
+                exc_info=True,
+            )
+            return EnvironmentDeploymentState(
+                environment=environment, active_resolution='error'
+            )
+        active: RemoteDeployment | None = None
+        latest: RemoteDeployment | None = None
+        scanned = 0
+        # Set by any row above the walk's stopping point that we could
+        # not read: a malformed listing entry, or one whose status
+        # history would not load.  Because the walk stops at the first
+        # clean success, every such row is *newer* than whatever success
+        # we go on to find, so it may itself be the deployment actually
+        # serving the environment.
+        unresolved = False
+        for deployment in deployments:
+            scanned += 1
+            observed = await self._observe_deployment(
+                client,
+                environment,
+                deployment,
+                run_cache,
+                release_lookups,
+                mainline,
+            )
+            if observed is None:
+                # A row we could not even identify.  It is still a row
+                # newer than any success below it, so it has to count as
+                # uncertainty rather than be skipped silently.
+                LOGGER.warning(
+                    'Active deployment scan could not identify a row for '
+                    'env=%s (id=%r sha=%r); resolving it as unreadable',
+                    environment,
+                    deployment.get('id'),
+                    deployment.get('sha'),
+                )
+                unresolved = True
+                continue
+            if latest is None:
+                latest = observed
+            if observed.status_unknown:
+                # Its status read failed, so this row's ``pending`` is a
+                # fallback.  Keep walking -- an older row may still
+                # answer -- but remember that the walk passed something
+                # it could not see.
+                unresolved = True
+            # ``status`` looks past GitHub's ``inactive`` notice on
+            # purpose, so a superseded rollout still reads as the
+            # ``success`` it was.  For "what is serving now" that notice
+            # is the answer, not noise: without the ``superseded`` test
+            # a deactivated environment reports its last success as
+            # active forever.  Walking on is safe -- an ``inactive``
+            # written because a later deployment took over has that
+            # deployment above it in this same newest-first page.
+            if observed.status == 'success' and not observed.superseded:
+                if unresolved:
+                    # A newer row we could not read sits above this
+                    # success, so we cannot claim this one is serving.
+                    # Stop here and report the uncertainty: the walk has
+                    # nothing older left to learn from.
+                    break
+                active = observed
+                break
+        # The result set is exhausted only when the walk read every row
+        # GitHub returned *and* GitHub returned fewer than we asked for
+        # (a full page means there is more history past the cap).  An
+        # empty listing does not count: GitHub answers 200 with ``[]``
+        # both for an environment that has never been deployed to and
+        # for an environment *name it has never heard of*, and the host
+        # passes local slugs through unmapped.  A project whose local
+        # slug is 'prod' against a remote 'production' would otherwise
+        # resolve ``none`` and have its pointer cleared on every sweep.
+        # Clearing needs positive evidence -- rows we read, none of them
+        # serving -- which is the deactivated-environment case.
+        exhausted = (
+            bool(deployments)
+            and scanned == len(deployments)
+            and scanned < scan_limit
+        )
+        resolution: typing.Literal['found', 'none', 'unknown', 'error']
+        if unresolved:
+            # Tested BEFORE ``found`` on purpose.  The walk stops at the
+            # first clean success, so every row it could not read is
+            # newer than that success -- and a 403 on the newest
+            # deployment's status hides exactly the deployment most
+            # likely to be serving.  Reporting ``found`` here would name
+            # an older release as current and have the host write that
+            # stale pointer.  ``error``, not ``none`` and not
+            # ``unknown``: the scan was not capped, it was blinded --
+            # most often by throttling, where every status read fails
+            # and ``none`` would clear every pointer on the project.
+            resolution = 'error'
+        elif active is not None:
+            resolution = 'found'
+        elif exhausted:
+            resolution = 'none'
+        else:
+            resolution = 'unknown'
+        LOGGER.info(
+            'Active deployment scan env=%s deployments_scanned=%d '
+            'unresolved_above_success=%s scan_exhausted=%s '
+            'active_resolution=%s',
+            environment,
+            scanned,
+            unresolved,
+            exhausted,
+            resolution,
+        )
+        return EnvironmentDeploymentState(
+            environment=environment,
+            active=active,
+            latest=latest,
+            active_resolution=resolution,
+        )
+
     async def get_release_notes(
         self,
         ctx: PluginContext,
@@ -1721,9 +2016,8 @@ class GitHubDeployment(DeploymentCapability):
         created_at = _parse_iso(deployment.get('created_at')) or (
             datetime.datetime.now(datetime.UTC)
         )
-        status, status_url = await self._latest_status(
-            client, str(deployment_id)
-        )
+        read = await self._latest_status(client, str(deployment_id))
+        status, status_url = read.status, read.log_url
         ref_value = deployment.get('ref')
         description = deployment.get('description')
         release_notes = (
@@ -1772,6 +2066,8 @@ class GitHubDeployment(DeploymentCapability):
             release_notes=release_notes,
             creator=creator_login,
             creator_subject=creator_subject,
+            superseded=read.superseded,
+            status_unknown=read.unreadable,
         )
 
     async def _resolve_triggering_actor(
@@ -1869,6 +2165,13 @@ class GitHubDeployment(DeploymentCapability):
         credits with the release and ``author_subject`` its numeric user
         id, which the host resolves to an Imbi user through the identity
         plugins on the same service.
+
+        A 401 degrades here too, like every other failure, rather than
+        propagating: release notes are *enrichment*, so losing them must
+        never fail the caller -- the same rule
+        :meth:`_resolve_triggering_actor` applies to attribution.  The
+        status read is deliberately not treated this way, because there
+        the answer itself is what a 401 hides.
         """
         if _releases_forbidden(client):
             return None
@@ -1876,7 +2179,7 @@ class GitHubDeployment(DeploymentCapability):
             resp = await client.get(
                 f'/releases/tags/{urllib.parse.quote(ref, safe="")}'
             )
-        except httpx.HTTPError:
+        except (httpx.HTTPError, PluginAuthenticationFailed):
             return None
         if resp.status_code == 403:
             _record_releases_forbidden(client)
@@ -1938,8 +2241,15 @@ class GitHubDeployment(DeploymentCapability):
 
     async def _latest_status(
         self, client: httpx.AsyncClient, deployment_id: str
-    ) -> tuple[DeploymentEventStatus, str | None]:
-        """Return the canonical event status + workflow log URL.
+    ) -> _StatusRead:
+        """Return the canonical event status, log URL, and retirement.
+
+        The third element is ``True`` when the newest status entry is
+        ``inactive``: the deployment's own outcome (the first element)
+        looks past that notice, so this is the only place the caller can
+        learn that GitHub has since retired it.  Both readings are
+        needed and neither substitutes for the other -- "what did this
+        rollout do" is a different question from "is it serving now".
 
         Falls back to ``'pending'`` whenever the deploy workflow has
         not yet posted a status: a freshly-created deployment with no
@@ -1975,15 +2285,35 @@ class GitHubDeployment(DeploymentCapability):
                 params={'per_page': '10'},
             )
         except httpx.HTTPError:
-            return 'pending', None
+            return _StatusRead(
+                'pending', None, superseded=False, unreadable=True
+            )
         if resp.status_code != 200:
-            return 'pending', None
+            # 403/429 land here, which is how a throttled scan used to
+            # read every row as ``pending`` and conclude that nothing was
+            # deployed.  The status is still ``pending`` for resync; the
+            # flag is what stops a currency decision resting on it.
+            LOGGER.warning(
+                'Deployment %s statuses answered %d; status unread',
+                deployment_id,
+                resp.status_code,
+            )
+            return _StatusRead(
+                'pending', None, superseded=False, unreadable=True
+            )
         try:
             statuses = typing.cast(list[dict[str, typing.Any]], resp.json())
         except ValueError:
-            return 'pending', None
+            return _StatusRead(
+                'pending', None, superseded=False, unreadable=True
+            )
         if not statuses:
-            return 'pending', None
+            # Read fine and there is genuinely nothing: a deployment
+            # whose workflow has not posted yet.  Not unreadable.
+            return _StatusRead(
+                'pending', None, superseded=False, unreadable=False
+            )
+        superseded = str(statuses[0].get('state') or '').lower() == 'inactive'
         latest = next(
             (
                 entry
@@ -1994,7 +2324,12 @@ class GitHubDeployment(DeploymentCapability):
         )
         state = str(latest.get('state') or '').lower()
         log_url = latest.get('log_url') or latest.get('target_url')
-        return _to_event_status(state), str(log_url) if log_url else None
+        return _StatusRead(
+            _to_event_status(state),
+            str(log_url) if log_url else None,
+            superseded=superseded,
+            unreadable=False,
+        )
 
 
 _RUN_ID_RE = re.compile(r'/actions/runs/(\d+)')

{imbi_plugin_github-2.28.0 → imbi_plugin_github-2.29.0}/src/imbi/plugins/github/plugin.py

@@ -97,6 +97,24 @@ _OPTIONS: list[PluginOption] = [
         required=False,
         default='main master',
     ),
+    PluginOption(
+        name='active_scan_limit',
+        label='Active deployment scan limit',
+        description=(
+            'How many deployments per environment the active-state scan '
+            'walks, newest-first, looking for the newest one whose latest '
+            'status is success.  Each row costs one status request.  Raise '
+            'it for repos whose environments see long runs of failed or '
+            'superseded deploys, where the live deployment sits deeper in '
+            'the history; hitting the limit reports the active deployment '
+            'as unknown rather than as absent.  Values above 100 are '
+            'clamped to 100, the most a single GitHub page can carry.  '
+            'Leave blank for the default of 10.'
+        ),
+        type='integer',
+        required=False,
+        default=10,
+    ),
 ]
 
 # The single credential store for the Integration. Every capability of

{imbi_plugin_github-2.28.0 → imbi_plugin_github-2.29.0}/tests/test_deployment.py

@@ -17,6 +17,7 @@ from imbi.common.plugins.base import (
 from imbi.common.plugins.errors import PluginAuthenticationFailed
 from imbi.plugins.github.deployment import (
     GitHubDeployment,
+    _active_scan_limit,
     _artifact_status,
     _mainline_branches,
     _repo_root_from_redirect,
@@ -57,6 +58,25 @@ def _ctx(
 _CREDS = {'access_token': 'gho_test'}
 
 
+def _deployment(deployment_id: int, created_at: str) -> dict[str, object]:
+    """A minimal ``GET /deployments`` row deploying a mainline branch."""
+    return {
+        'id': deployment_id,
+        'sha': f'sha{deployment_id}',
+        'ref': 'main',
+        'created_at': created_at,
+    }
+
+
+def _statuses(*states: str) -> None:
+    """Mock ``/deployments/{id}/statuses`` for ids 1..len(states)."""
+    for offset, state in enumerate(states, start=1):
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/'
+            f'{offset}/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': state}]))
+
+
 class ManifestTestCase(unittest.TestCase):
     def test_manifest_slug(self) -> None:
         self.assertEqual(GitHubPlugin.manifest.slug, 'github')
@@ -108,6 +128,14 @@ class ManifestTestCase(unittest.TestCase):
             'mainline_branches', {opt.name for opt in cap.options}
         )
 
+    def test_active_scan_limit_declared_integration_level(self) -> None:
+        # Scan depth follows the org's deploy habits, like mainline
+        # branch naming, so it sits beside flavor/host on the Integration.
+        options = {opt.name: opt for opt in GitHubPlugin.manifest.options}
+        self.assertIn('active_scan_limit', options)
+        self.assertEqual(options['active_scan_limit'].default, 10)
+        self.assertFalse(options['active_scan_limit'].required)
+
     def test_no_legacy_deploys_via_edge_declared(self) -> None:
         # Promote behaviour is inferred from the ref shape and per-env
         # payloads ride on the USES edge (``env_payloads``).  No plugin
@@ -1920,6 +1948,460 @@ class ListRecentDeploymentsTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(events[0].creator_subject, '583231')
 
 
+class GetEnvironmentStateTestCase(unittest.IsolatedAsyncioTestCase):
+    @respx.mock
+    async def test_newest_success_is_active(self) -> None:
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T14:00:00Z')]
+            )
+        )
+        _statuses('success')
+        plugin = GitHubDeployment()
+        states = await plugin.get_environment_state(
+            _ctx(), _CREDS, ['production']
+        )
+        self.assertEqual(len(states), 1)
+        state = states[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        assert state.latest is not None
+        self.assertEqual(state.active.external_run_id, '1')
+        # The newest attempt is also the active one here, and both carry
+        # the same ``RemoteDeployment`` shape resync records.
+        self.assertEqual(state.latest.external_run_id, '1')
+        self.assertEqual(state.active.status, 'success')
+
+    @respx.mock
+    async def test_newest_failed_older_success_stays_active(self) -> None:
+        # The original bug: the newest attempt failed, so the deployment
+        # actually serving the environment is the older success.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        _statuses('failure', 'success')
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        assert state.latest is not None
+        self.assertEqual(state.active.external_run_id, '2')
+        self.assertEqual(state.latest.external_run_id, '1')
+        self.assertEqual(state.latest.status, 'failed')
+
+    @respx.mock
+    async def test_newest_pending_older_success_stays_active(self) -> None:
+        # An in-flight deploy is activity, not currency: the older
+        # success is still what serves traffic.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        _statuses('in_progress', 'success')
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        assert state.latest is not None
+        self.assertEqual(state.active.external_run_id, '2')
+        self.assertEqual(state.latest.status, 'in_progress')
+
+    @respx.mock
+    async def test_retired_success_is_not_active(self) -> None:
+        # GitHub wrote ``inactive`` on top of the success, so nothing is
+        # serving this environment any more.  ``status`` still reads
+        # ``success`` -- the rollout did succeed -- which is exactly why
+        # the scan cannot answer from ``status`` alone.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T14:00:00Z')]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[{'state': 'inactive'}, {'state': 'success'}]
+            )
+        )
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'none')
+        self.assertIsNone(state.active)
+        assert state.latest is not None
+        self.assertEqual(state.latest.status, 'success')
+        self.assertTrue(state.latest.superseded)
+
+    @respx.mock
+    async def test_scan_walks_past_a_retired_success(self) -> None:
+        # The newest deployment was retired; the one below it is what
+        # the environment is actually serving.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[{'state': 'inactive'}, {'state': 'success'}]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/2/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': 'success'}]))
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        self.assertEqual(state.active.external_run_id, '2')
+        self.assertFalse(state.active.superseded)
+        assert state.latest is not None
+        self.assertEqual(state.latest.external_run_id, '1')
+
+    @respx.mock
+    async def test_scan_cap_reached_is_unknown_never_none(self) -> None:
+        # A full page with no success means an older active deployment
+        # may sit just past the cap — reporting 'none' would have the
+        # host clear a pointer that is right.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '2'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        _statuses('failure', 'failure')
+        plugin = GitHubDeployment()
+        ctx = _ctx(connection=_connection() | {'active_scan_limit': 2})
+        state = (
+            await plugin.get_environment_state(ctx, _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'unknown')
+        self.assertIsNone(state.active)
+        assert state.latest is not None
+        self.assertEqual(state.latest.external_run_id, '1')
+
+    @respx.mock
+    async def test_no_deployments_is_unknown_not_none(self) -> None:
+        # GitHub answers 200 with ``[]`` both for an environment nothing
+        # has deployed to and for an environment name it has never heard
+        # of -- and local slugs reach it unmapped, so a project whose
+        # slug is 'prod' against a remote 'production' looks identical to
+        # an empty environment.  ``none`` clears the pointer, so an empty
+        # listing must not earn it.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(return_value=httpx.Response(200, json=[]))
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'unknown')
+        self.assertIsNone(state.active)
+        self.assertIsNone(state.latest)
+
+    @respx.mock
+    async def test_short_page_without_success_is_none(self) -> None:
+        # Fewer rows than the cap means the history is exhausted, so
+        # "nothing is deployed" is a real answer.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T15:00:00Z')]
+            )
+        )
+        _statuses('failure')
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'none')
+        self.assertIsNone(state.active)
+        assert state.latest is not None
+        self.assertEqual(state.latest.status, 'failed')
+
+    @respx.mock
+    async def test_provider_failure_is_error_not_none(self) -> None:
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(503, json={'message': 'unavailable'})
+        )
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'error')
+        self.assertIsNone(state.active)
+        self.assertIsNone(state.latest)
+
+    @respx.mock
+    async def test_a_404_listing_is_error_not_none(self) -> None:
+        # NOT ``none``, unlike ``list_recent_deployments``: here ``none``
+        # authorizes clearing the pointer, and a 404 is what a renamed or
+        # transferred repo -- or a token that lost access -- answers.  An
+        # unknown *environment* is a 200 with an empty list.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T15:00:00Z')]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'never-deployed', 'per_page': '10'},
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        _statuses('success')
+        plugin = GitHubDeployment()
+        with self.assertLogs('imbi.plugins.github', level='WARNING'):
+            states = await plugin.get_environment_state(
+                _ctx(), _CREDS, ['production', 'never-deployed']
+            )
+        by_env = {s.environment: s for s in states}
+        self.assertEqual(by_env['production'].active_resolution, 'found')
+        missing = by_env['never-deployed']
+        self.assertEqual(missing.active_resolution, 'error')
+        self.assertIsNone(missing.active)
+        self.assertIsNone(missing.latest)
+
+    @respx.mock
+    async def test_an_unread_status_is_error_not_none(self) -> None:
+        # A throttled scan reads every status as the ``pending``
+        # fallback.  Answering ``none`` there would clear a pointer that
+        # is right, on every environment of the project at once.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T15:00:00Z')]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                403, json={'message': 'API rate limit exceeded'}
+            )
+        )
+        plugin = GitHubDeployment()
+        with self.assertLogs('imbi.plugins.github', level='WARNING'):
+            state = (
+                await plugin.get_environment_state(
+                    _ctx(), _CREDS, ['production']
+                )
+            )[0]
+        self.assertEqual(state.active_resolution, 'error')
+        self.assertIsNone(state.active)
+        assert state.latest is not None
+        self.assertTrue(state.latest.status_unknown)
+
+    @respx.mock
+    async def test_a_success_above_an_unread_status_still_answers(
+        self,
+    ) -> None:
+        # The walk stops at the first live success, so rows it never
+        # reached cannot outrank it -- reading them is not required.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': 'success'}]))
+        unread = respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/2/statuses'
+        ).mock(return_value=httpx.Response(500))
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        self.assertEqual(state.active.external_run_id, '1')
+        self.assertFalse(unread.called)
+
+    @respx.mock
+    async def test_an_unread_row_above_a_success_is_error(self) -> None:
+        # The mirror of the test above, and the case that matters: the
+        # unread row is NEWER than the success.  The walk stops at the
+        # first clean success, so anything it could not read sits above
+        # that success and may be the deployment actually serving the
+        # environment.  Answering ``found`` here would name the older
+        # release as current and have the host write a stale pointer.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    _deployment(1, '2026-05-13T15:00:00Z'),
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                403, json={'message': 'API rate limit exceeded'}
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/2/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': 'success'}]))
+        plugin = GitHubDeployment()
+        with self.assertLogs('imbi.plugins.github', level='WARNING'):
+            state = (
+                await plugin.get_environment_state(
+                    _ctx(), _CREDS, ['production']
+                )
+            )[0]
+        self.assertEqual(state.active_resolution, 'error')
+        self.assertIsNone(state.active)
+        # ``latest`` still reports the newest attempt, unread status and
+        # all -- it is activity, never currency.
+        assert state.latest is not None
+        self.assertEqual(state.latest.external_run_id, '1')
+        self.assertTrue(state.latest.status_unknown)
+
+    @respx.mock
+    async def test_a_malformed_row_above_a_success_is_error(self) -> None:
+        # A row too malformed to identify is just as unreadable as one
+        # whose status would not load, and it is newer than the success
+        # below it.  Skipping it silently would report that success as
+        # active.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {'id': None, 'sha': None, 'created_at': None},
+                    _deployment(2, '2026-05-13T14:00:00Z'),
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/2/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': 'success'}]))
+        plugin = GitHubDeployment()
+        with self.assertLogs('imbi.plugins.github', level='WARNING'):
+            state = (
+                await plugin.get_environment_state(
+                    _ctx(), _CREDS, ['production']
+                )
+            )[0]
+        self.assertEqual(state.active_resolution, 'error')
+        self.assertIsNone(state.active)
+        # The malformed row cannot be reported at all, so ``latest``
+        # names the readable success below it even though nothing is
+        # claimed active.  That pairing is the surprising part of the
+        # contract, so pin it.
+        assert state.latest is not None
+        self.assertEqual(state.latest.external_run_id, '2')
+
+    @respx.mock
+    async def test_an_empty_status_list_is_not_unread(self) -> None:
+        # Read fine, nothing posted yet: that is a real ``pending``, and
+        # an exhausted page of them is a real "nothing deployed".
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T15:00:00Z')]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(return_value=httpx.Response(200, json=[]))
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'none')
+        assert state.latest is not None
+        self.assertFalse(state.latest.status_unknown)
+
+
+class ActiveScanLimitTestCase(unittest.TestCase):
+    def test_absent_option_uses_default(self) -> None:
+        self.assertEqual(_active_scan_limit({}), 10)
+
+    def test_string_option_parsed(self) -> None:
+        # The admin form hands scalar options back as strings.
+        self.assertEqual(_active_scan_limit({'active_scan_limit': '25'}), 25)
+
+    def test_invalid_or_out_of_range_values_fall_back(self) -> None:
+        self.assertEqual(_active_scan_limit({'active_scan_limit': 'ten'}), 10)
+        self.assertEqual(_active_scan_limit({'active_scan_limit': 0}), 10)
+        self.assertEqual(_active_scan_limit({'active_scan_limit': True}), 10)
+        # One GitHub page is the ceiling.
+        self.assertEqual(_active_scan_limit({'active_scan_limit': 500}), 100)
+
+
 class GetReleaseNotesTestCase(unittest.IsolatedAsyncioTestCase):
     @respx.mock
     async def test_returns_release_body_for_tag(self) -> None:
@@ -2158,6 +2640,69 @@ class AuthenticationFailureTestCase(unittest.IsolatedAsyncioTestCase):
         with self.assertRaises(PluginAuthenticationFailed):
             await plugin.list_refs(_ctx(), _CREDS, kind='default')
 
+    @respx.mock
+    async def test_401_on_release_lookup_degrades(self) -> None:
+        # Release notes are enrichment, so a 401 fetching them degrades
+        # to "no notes" instead of propagating -- the same rule
+        # attribution follows.  The status read is deliberately NOT
+        # treated this way; see the test below.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'id': 1,
+                        'sha': 'sha1',
+                        'ref': 'v1.2.3',
+                        'created_at': '2026-05-13T15:00:00Z',
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(return_value=httpx.Response(200, json=[{'state': 'success'}]))
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/v1.2.3'
+        ).mock(
+            return_value=httpx.Response(401, json={'message': 'token expired'})
+        )
+        plugin = GitHubDeployment()
+        state = (
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+        )[0]
+        self.assertEqual(state.active_resolution, 'found')
+        assert state.active is not None
+        self.assertEqual(state.active.external_run_id, '1')
+        self.assertIsNone(state.active.release_notes)
+
+    @respx.mock
+    async def test_401_on_status_read_still_propagates(self) -> None:
+        # The counterpart guarantee: a 401 on the status read must reach
+        # the host, because ``call_with_identity_retry`` is what refreshes
+        # the identity and retries the scan.  Swallowing it here would
+        # leave every environment resolving ``error`` on an expired token
+        # with no refresh ever attempted.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments',
+            params={'environment': 'production', 'per_page': '10'},
+        ).mock(
+            return_value=httpx.Response(
+                200, json=[_deployment(1, '2026-05-13T15:00:00Z')]
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/1/statuses'
+        ).mock(
+            return_value=httpx.Response(401, json={'message': 'token expired'})
+        )
+        plugin = GitHubDeployment()
+        with self.assertRaises(PluginAuthenticationFailed):
+            await plugin.get_environment_state(_ctx(), _CREDS, ['production'])
+
     @respx.mock
     async def test_401_on_deployment_raises_authentication_failed(
         self,
@@ -3131,6 +3676,33 @@ class GitNotesTestCase(unittest.IsolatedAsyncioTestCase):
         )
         self.assertTrue(listing.complete)
 
+    @respx.mock
+    async def test_list_commit_notes_skips_answered_commits(self) -> None:
+        # Enumerating the ref is a call or two; every body is a request
+        # of its own, so a caller repairing a gap must be able to pay
+        # only for what it is missing.
+        other_sha = 'e' * 40
+        self._mock_tree(
+            [
+                {'type': 'blob', 'path': self.FULL_SHA, 'sha': 'b1'},
+                {'type': 'blob', 'path': other_sha, 'sha': 'b2'},
+            ]
+        )
+        skipped = respx.get(f'{self.REPO}/git/blobs/b1').mock(
+            return_value=httpx.Response(500)
+        )
+        self._blob('b2', '{"drift_detected":false}')
+        listing = await self.handler.list_commit_notes(
+            _ctx(), _CREDS, 'imbi-drift', skip_shas=[self.FULL_SHA.upper()]
+        )
+        self.assertFalse(skipped.called)
+        self.assertEqual(
+            {other_sha: '{"drift_detected":false}'}, listing.notes
+        )
+        # A note skipped on request is not a note that could not be
+        # read: the caller already holds that answer.
+        self.assertTrue(listing.complete)
+
     @respx.mock
     async def test_list_commit_notes_reports_an_unreadable_blob(self) -> None:
         # The readable note still comes back, but the listing says it is