imbi-plugin-github 1.3.0__tar.gz → 1.5.0__tar.gz

imbi_plugin_github-1.5.0/CLAUDE.md

@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+A set of GitHub plugins for the Imbi platform, distributed as a single
+Python package (`imbi_plugin_github`). It ships **three plugin types**
+(identity, deployment, lifecycle), each in **three host flavors**
+(github.com, GitHub Enterprise Cloud, GitHub Enterprise Server) — nine
+plugins total. The Imbi host discovers them through the
+`imbi.plugins` entry points declared in `pyproject.toml`; that table is
+the registration surface — adding a plugin class means adding an entry
+point there.
+
+All plugin base classes (`IdentityPlugin`, `DeploymentPlugin`,
+`LifecyclePlugin`, `PluginContext`, `PluginManifest`, the result/dataclass
+types) come from `imbi_common.plugins.base`. That module is the contract
+this package implements against; read it (in the sibling `imbi-common`
+repo) before changing a plugin's method signatures.
+
+## Commands
+
+```bash
+just setup              # uv sync --all-groups --all-extras + install pre-commit hooks
+just test               # coverage run -m pytest tests + coverage report/xml (fails under 85%)
+just test tests/test_lifecycle.py                       # one file
+just test tests/test_lifecycle.py::ManifestTestCase     # one class/test (passed straight to pytest)
+just lint               # pre-commit run --all-files (ruff, ruff-format, tombi, basedpyright)
+just format [FILES]     # ruff-format + tombi-format
+```
+
+`just test` with arguments skips the coverage wrapper and runs `pytest`
+directly. `.env`, if present, is passed via `--env-file` (not required
+for the test suite). Type checking is `basedpyright` in **strict** mode
+over `src`. Python is pinned to **3.14**; ruff uses single quotes and a
+79-char line length.
+
+## Architecture
+
+### The base/subclass/host-flavor pattern
+
+Every plugin type follows the same shape: one `_*Base` class holds all
+behavior, and three thin concrete subclasses differ *only* in their
+`_resolve_host(options)` classmethod:
+
+- github.com flavor → returns `'github.com'`.
+- GHEC flavor → reads the required `host` option, validates it's a
+  `*.ghe.com` tenant via `require_ghec_tenant_host`.
+- GHES flavor → reads the required `host` option, normalized only.
+
+`_resolve_host` feeds URL construction, and the three backends route
+differently — this mapping is the single most important thing to keep
+consistent and is **duplicated** across the three modules
+(`identity._endpoints`, `deployment._api_base`, `lifecycle._api_base`):
+
+| Host                | REST API base                  | OAuth base (identity only)        |
+| ------------------- | ------------------------------ | --------------------------------- |
+| `github.com`        | `https://api.github.com`       | `https://github.com/login/oauth`  |
+| `<tenant>.ghe.com`  | `https://api.<tenant>.ghe.com` | `https://<tenant>.ghe.com/login/oauth` |
+| GHES `<host>`       | `https://<host>/api/v3`        | `https://<host>/login/oauth`      |
+
+When you change routing for one plugin type, check whether the other two
+need the same change.
+
+### Shared helpers (single sources of truth)
+
+- `_hosts.py` — `normalize_host` (strip/validate a bare hostname, reject
+  paths/ports/queries) and `require_ghec_tenant_host`. All host-option
+  validation lives here.
+- `_repos.py` — `resolve_owner_repo(ctx, host, label)` derives the target
+  `(owner, repo)` for deployment and lifecycle calls: it scans
+  `ctx.project_links` (preferring the `github-repository` key, skipping
+  reserved GitHub path prefixes like `/orgs/`), then falls back to
+  `<project_type_slug>/<project_slug>`, and raises `ValueError` with an
+  operator-facing message when neither works.
+
+### Plugin invocation contract
+
+Plugins are **stateless and single-shot**: the host constructs the
+plugin once and calls methods passing `PluginContext` plus a
+`credentials` dict per call. Identity plugins mint the OAuth access
+token; deployment and lifecycle plugins consume it via
+`credentials['access_token']` (with a `'token'` fallback) and send it as
+a `Bearer` header. A `401` response is converted to
+`PluginAuthenticationFailed` by an httpx response hook so the host's
+retry layer can refresh the actor's identity once before failing the
+user-visible request.
+
+### Behaviors that span multiple files / aren't obvious from one method
+
+- **Deployment uses the GitHub Deployments API**, not
+  `workflow_dispatch`: Imbi's `Environment` maps 1:1 to GitHub's
+  `environment` so protection rules apply server-side. `trigger_deployment`
+  sends `auto_merge=False` and `required_contexts=[]` deliberately.
+  Promote behavior (semver tag → Deployment vs. raw SHA → tag + Release)
+  is decided **host-side** in imbi-api, not here. Per-environment workflow
+  inputs ride on the `USES_PLUGIN` graph edge as `env_payloads` and arrive
+  as `ctx.environment_config`.
+- **`/check-runs` 403 cache** in `deployment.py`: a process-wide,
+  TTL'd cache (keyed by a hash of token+host+repo) suppresses repeated
+  403s when the token lacks scope or Actions is disabled, so opening a
+  deploy dialog doesn't fire one wasted 403 per commit.
+- **Lifecycle archive-with-transfer dance** (`lifecycle.py`): when
+  `archive_target_org` is set, archive transfers the repo there first.
+  GitHub refuses to transfer an *archived* repo, so an already-archived
+  source is briefly unarchived → transferred → re-archived. GitHub's
+  transfer is **async** (returns 202, repo briefly 404s at the
+  destination), so the post-transfer archive PATCH retries on 404 with a
+  bounded backoff (`_TRANSFER_ARCHIVE_BACKOFFS`). Unarchive only flips
+  `archived` back at the repo's current location — it never transfers
+  back, because the original owner isn't tracked.
+
+## Testing
+
+Tests mock GitHub's HTTP with **respx** (`asyncio_mode = auto`, so async
+tests need no decorator). Each test builds a `PluginContext` with a
+`github-repository` project link and passes `{'access_token': ...}`
+credentials, mirroring how the host calls in. When adding a GitHub API
+call, add the matching respx route. Coverage must stay ≥ 85%.
+
+## Dependency Management
+
+`pyproject.toml` pins the package to PyPI (`pypi.org`) with a 7-day
+`exclude-newer` holdback on third-party packages; the imbi-common and
+`imbi-plugin-*` packages are exempt via `exclude-newer-package` so local
+ecosystem changes aren't held back. After changing dependencies, run
+`uv sync` and verify `uv.lock`.

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbi-plugin-github
-Version: 1.3.0
+Version: 1.5.0
 Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
 Author-email: "Gavin M. Roy" <gavinr@aweber.com>
 License: BSD-3-Clause
@@ -13,7 +13,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>=2.5.5
+Requires-Dist: imbi-common>=2.7.0
 Requires-Dist: pydantic>=2
 Description-Content-Type: text/markdown
 
@@ -33,9 +33,9 @@ projects to the right backend.
 
 ### Identity
 
-Phase 1 ships the OAuth App flow only; GitHub App installation tokens are
-deferred. The access token returned by the OAuth grant is passed straight
-to GitHub APIs as a `Bearer` token, so `materialize()` is a no-op.
+Implements the OAuth App flow. The access token returned by the OAuth
+grant is passed straight to GitHub APIs as a `Bearer` token, so
+`materialize()` is a no-op.
 
 ### Deployment
 
@@ -68,7 +68,7 @@ requires admin permission on the target organization.
 | Option           | Required  | Description                                                                |
 | ---------------- | --------- | -------------------------------------------------------------------------- |
 | `host`           | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`).    |
-| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email`).    |
+| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email repo workflow`). |
 
 ## Credentials (identity)
 

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/README.md

@@ -14,9 +14,9 @@ projects to the right backend.
 
 ### Identity
 
-Phase 1 ships the OAuth App flow only; GitHub App installation tokens are
-deferred. The access token returned by the OAuth grant is passed straight
-to GitHub APIs as a `Bearer` token, so `materialize()` is a no-op.
+Implements the OAuth App flow. The access token returned by the OAuth
+grant is passed straight to GitHub APIs as a `Bearer` token, so
+`materialize()` is a no-op.
 
 ### Deployment
 
@@ -49,7 +49,7 @@ requires admin permission on the target organization.
 | Option           | Required  | Description                                                                |
 | ---------------- | --------- | -------------------------------------------------------------------------- |
 | `host`           | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`).    |
-| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email`).    |
+| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email repo workflow`). |
 
 ## Credentials (identity)
 

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "1.3.0"
+version = "1.5.0"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -16,7 +16,7 @@ classifiers = [
 ]
 dependencies = [
   "httpx>=0.27",
-  "imbi-common>=2.5.5",
+  "imbi-common>=2.7.0",
   "pydantic>=2",
 ]
 
@@ -121,6 +121,8 @@ max-complexity = 15
 
 [tool.uv]
 default-groups = ["dev"]
+exclude-newer = "7 days"
+exclude-newer-package = { "clickhouse-connect" = false, "imbi-common" = false, "imbi-plugin-aws" = false, "imbi-plugin-github" = false, "imbi-plugin-logzio" = false, "imbi-plugin-oidc" = false, "imbi-plugin-pagerduty" = false, "imbi-plugin-sentry" = false, "imbi-plugin-sonarqube" = false }
 
 [[tool.uv.index]]
 url = "https://pypi.org/simple"

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/src/imbi_plugin_github/deployment.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 
 import asyncio
 import collections.abc
+import contextlib
 import datetime
 import hashlib
 import logging
@@ -50,6 +51,7 @@ from imbi_common.plugins.base import (
     RefInfo,
     ReleaseInfo,
     RemoteDeployment,
+    RepositoryRelocation,
     WorkflowFile,
 )
 from imbi_common.plugins.errors import PluginAuthenticationFailed
@@ -159,6 +161,30 @@ def _parse_iso(value: str | None) -> datetime.datetime | None:
         return None
 
 
+def _repo_root_from_redirect(location: str) -> str | None:
+    """Derive the canonical repo-root URL from a rename redirect target.
+
+    GitHub answers a request to a renamed repo with a ``301`` whose
+    ``Location`` points at the by-id form, e.g.
+    ``https://api.host/repositories/687046/commits``.  Strip the
+    sub-resource path back to ``https://api.host/repositories/687046`` so
+    we can ``GET`` it for the repo's current ``full_name``/``html_url``.
+    Returns ``None`` when ``location`` isn't a ``/repositories/{id}`` URL.
+    """
+    parsed = urllib.parse.urlsplit(location)
+    parts = [segment for segment in parsed.path.split('/') if segment]
+    try:
+        idx = parts.index('repositories')
+    except ValueError:
+        return None
+    if idx + 1 >= len(parts):
+        return None
+    repo_id = parts[idx + 1]
+    return urllib.parse.urlunsplit(
+        (parsed.scheme, parsed.netloc, f'/repositories/{repo_id}', '', '')
+    )
+
+
 def _checks_cache_key(
     credentials: dict[str, str], host: str, owner: str, repo: str
 ) -> str | None:
@@ -318,14 +344,86 @@ class _DeploymentBase(DeploymentPlugin):
             )
         return token
 
-    def _client(
+    @contextlib.asynccontextmanager
+    async def _client(
         self, ctx: PluginContext, credentials: dict[str, str]
-    ) -> httpx.AsyncClient:
-        return httpx.AsyncClient(
+    ) -> collections.abc.AsyncGenerator[httpx.AsyncClient]:
+        """Yield an httpx client that survives — and self-heals — renames.
+
+        ``follow_redirects=True`` means a renamed repo's ``301`` is
+        followed and the request transparently retried against the
+        canonical ``/repositories/{id}`` location instead of crashing in
+        ``raise_for_status``.  A response hook records that redirect; once
+        the caller's request succeeds we resolve the repo's new
+        ``full_name``/``html_url`` and stash a
+        :class:`~imbi_common.plugins.base.RepositoryRelocation` on ``ctx``
+        so the host can self-heal the project's stored link.  This is the
+        single chokepoint for every deployment call.
+        """
+        captured: list[str] = []
+
+        async def _capture_redirect(response: httpx.Response) -> None:
+            if response.is_redirect:
+                location = response.headers.get('location') or ''
+                if '/repositories/' in location:
+                    captured.append(location)
+
+        client = httpx.AsyncClient(
             timeout=_HTTP_TIMEOUT_SECONDS,
             headers=_auth_headers(self._token(credentials)),
             base_url=self._repo_url(ctx),
-            event_hooks={'response': [_raise_on_401]},
+            follow_redirects=True,
+            event_hooks={'response': [_capture_redirect, _raise_on_401]},
+        )
+        async with client:
+            yield client
+            # Only after the caller's request succeeded: a captured
+            # redirect means the repo was renamed out from under the
+            # stored link.  Resolve the new name once and report it.
+            if captured and ctx.repository_relocation is None:
+                await self._record_relocation(client, ctx, captured[-1])
+
+    async def _record_relocation(
+        self,
+        client: httpx.AsyncClient,
+        ctx: PluginContext,
+        redirect_location: str,
+    ) -> None:
+        """Resolve a renamed repo's canonical name and stash it on ``ctx``.
+
+        Best-effort: any failure to resolve the repo root leaves
+        ``ctx.repository_relocation`` unset so the user-facing call (which
+        already succeeded via the followed redirect) is never disturbed.
+        """
+        repo_root = _repo_root_from_redirect(redirect_location)
+        if repo_root is None:
+            return
+        try:
+            resp = await client.get(repo_root)
+        except (httpx.HTTPError, PluginAuthenticationFailed):
+            # The user-facing request already succeeded; a probe failure
+            # (network, or a 401 surfaced by the response hook) must not
+            # turn that success into an error during teardown.
+            return
+        if resp.status_code != 200:
+            return
+        try:
+            payload = typing.cast(dict[str, typing.Any], resp.json())
+        except ValueError:
+            return
+        full_name = str(payload.get('full_name') or '')
+        html_url = str(payload.get('html_url') or '')
+        if not full_name or not html_url:
+            return
+        old_owner, old_repo = self._owner_repo(ctx)
+        old_owner_repo = f'{old_owner}/{old_repo}'
+        if full_name.lower() == old_owner_repo.lower():
+            return
+        ctx.repository_relocation = RepositoryRelocation(
+            link_key='github-repository',
+            new_url=html_url,
+            old_owner_repo=old_owner_repo,
+            new_owner_repo=full_name,
         )
 
     # -- Refs ---------------------------------------------------------------
@@ -580,7 +678,7 @@ class _DeploymentBase(DeploymentPlugin):
                 deletions=deletions,
             )
 
-    # -- Tags / Releases (Phase 2 — implemented here for completeness) -----
+    # -- Tags / Releases ----------------------------------------------------
 
     async def create_tag(
         self,

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/src/imbi_plugin_github/identity.py

@@ -7,9 +7,8 @@ Three concrete subclasses share one base and differ only by host:
 * :class:`GitHubEnterpriseServerPlugin` — operator-managed GHES; the
   hostname comes from a manifest option.
 
-Phase 1 implements the OAuth App flow only.  GitHub App installation
-tokens (org-scoped automation) are deferred — service principals
-continue to use the legacy ``ServiceApplication`` model.
+The plugins implement the OAuth App flow: the access token from the
+OAuth grant is passed straight to GitHub APIs as a ``Bearer`` token.
 """
 
 from __future__ import annotations

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/src/imbi_plugin_github/lifecycle.py

@@ -20,6 +20,16 @@ On project archive the plugin:
 3. Archives the repo via ``PATCH /repos/{owner}/{repo}`` with
    ``{"archived": true}``.
 
+GitHub's repo transfer is asynchronous: ``POST .../transfer`` returns
+``202 Accepted`` and the repo is briefly unreachable at the
+destination owner.  A PATCH fired immediately after the transfer
+therefore 404s, leaving the repo transferred-but-not-archived (see
+the ``archives`` org incidents on the GHEC tenant).  The post-transfer
+archive is retried on 404 with a bounded backoff so the common case
+(transfer settles within a few seconds) succeeds, while a genuinely
+stuck transfer still fails fast enough to stay inside the dispatcher's
+per-plugin timeout and surface to the operator.
+
 On unarchive the plugin only flips ``archived`` back to ``false`` at
 the repo's current location — it does **not** attempt to transfer
 the repo back to its original org because the original owner is not
@@ -35,6 +45,7 @@ target organization.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import typing
 
@@ -46,6 +57,7 @@ from imbi_common.plugins.base import (
     PluginContext,
     PluginManifest,
     PluginOption,
+    RepositoryRelocation,
 )
 from imbi_common.plugins.errors import PluginAuthenticationFailed
 
@@ -56,6 +68,13 @@ LOGGER = logging.getLogger(__name__)
 
 _HTTP_TIMEOUT_SECONDS = 10.0
 
+# Backoffs (seconds) between attempts to archive a freshly-transferred
+# repo while GitHub's async transfer settles.  len + 1 == total
+# attempts; the sum is kept well under the dispatcher's per-plugin
+# timeout (default 10s) so a stuck transfer fails fast rather than
+# hanging the operator's archive request.
+_TRANSFER_ARCHIVE_BACKOFFS: tuple[float, ...] = (0.5, 1.0, 2.0)
+
 
 async def _raise_on_401(response: httpx.Response) -> None:
     """Convert a 401 from GitHub into :class:`PluginAuthenticationFailed`.
@@ -111,10 +130,16 @@ class _LifecycleBase(LifecyclePlugin):
     def _client(
         self, ctx: PluginContext, credentials: dict[str, str]
     ) -> httpx.AsyncClient:
+        # follow_redirects so a repo renamed outside Imbi (GitHub answers
+        # the stale ``/repos/{owner}/{repo}`` path with a 301 to the by-id
+        # form) is followed instead of crashing in ``raise_for_status``.
+        # The canonical owner/repo are then adopted from the repo payload;
+        # see ``on_project_archived``.
         return httpx.AsyncClient(
             timeout=_HTTP_TIMEOUT_SECONDS,
             headers=_auth_headers(self._token(credentials)),
             base_url=self._api_base(ctx.assignment_options),
+            follow_redirects=True,
             event_hooks={'response': [_raise_on_401]},
         )
 
@@ -136,8 +161,18 @@ class _LifecycleBase(LifecyclePlugin):
 
         async with self._client(ctx, credentials) as client:
             current = await self._get_repo(client, owner, repo)
-            already_archived = bool(current.get('archived'))
             current_owner = self._current_owner(current, owner)
+            current_repo = self._current_repo(current, repo)
+            # If the repo moved out from under the stored link *before*
+            # we touched it (an external rename), report it so the host
+            # self-heals the link.  This is computed before any transfer
+            # we initiate below, so an intentional archive-org transfer
+            # is never mistaken for an external relocation.
+            self._maybe_report_relocation(
+                ctx, host, current, owner, repo, current_owner, current_repo
+            )
+            repo = current_repo
+            already_archived = bool(current.get('archived'))
 
             needs_transfer = bool(
                 target_org and current_owner.lower() != target_org.lower()
@@ -151,7 +186,9 @@ class _LifecycleBase(LifecyclePlugin):
                         'archived'
                     ),
                     artifacts={
-                        'repo_url': self._repo_html_url(host, owner, repo),
+                        'repo_url': self._repo_html_url(
+                            host, current_owner, repo
+                        ),
                     },
                 )
 
@@ -172,8 +209,11 @@ class _LifecycleBase(LifecyclePlugin):
                 repo = str(transferred.get('name') or repo)
                 owner = target_org or current_owner
                 current_owner = owner
-
-            await self._set_archived(client, current_owner, repo, True)
+                # The repo may not be reachable at the destination
+                # owner yet; tolerate the transfer-settle 404 window.
+                await self._archive_after_transfer(client, current_owner, repo)
+            else:
+                await self._set_archived(client, current_owner, repo, True)
 
         return LifecycleResult(
             status='ok',
@@ -193,6 +233,11 @@ class _LifecycleBase(LifecyclePlugin):
         async with self._client(ctx, credentials) as client:
             current = await self._get_repo(client, owner, repo)
             current_owner = self._current_owner(current, owner)
+            current_repo = self._current_repo(current, repo)
+            self._maybe_report_relocation(
+                ctx, host, current, owner, repo, current_owner, current_repo
+            )
+            repo = current_repo
             if not current.get('archived'):
                 return LifecycleResult(
                     status='skipped',
@@ -225,6 +270,49 @@ class _LifecycleBase(LifecyclePlugin):
                 return login
         return fallback
 
+    @staticmethod
+    def _current_repo(payload: dict[str, typing.Any], fallback: str) -> str:
+        """Return the repo name from a repo payload, fallback when absent."""
+        name = payload.get('name')
+        if isinstance(name, str) and name:
+            return name
+        return fallback
+
+    def _maybe_report_relocation(
+        self,
+        ctx: PluginContext,
+        host: str,
+        payload: dict[str, typing.Any],
+        link_owner: str,
+        link_repo: str,
+        current_owner: str,
+        current_repo: str,
+    ) -> None:
+        """Record a relocation when the repo moved out from under the link.
+
+        Compares the link-derived ``<owner>/<repo>`` against the repo's
+        canonical name from ``payload``.  When they differ the repo was
+        renamed (or its owner renamed) outside Imbi, so stash a
+        :class:`RepositoryRelocation` on ``ctx`` for the host to self-heal
+        the stored link.  No-op when they match.
+        """
+        old_owner_repo = f'{link_owner}/{link_repo}'
+        new_owner_repo = f'{current_owner}/{current_repo}'
+        if new_owner_repo.lower() == old_owner_repo.lower():
+            return
+        html_url = payload.get('html_url')
+        new_url = (
+            html_url
+            if isinstance(html_url, str) and html_url
+            else self._repo_html_url(host, current_owner, current_repo)
+        )
+        ctx.repository_relocation = RepositoryRelocation(
+            link_key='github-repository',
+            new_url=new_url,
+            old_owner_repo=old_owner_repo,
+            new_owner_repo=new_owner_repo,
+        )
+
     @staticmethod
     def _repo_html_url(host: str, owner: str, repo: str) -> str:
         return f'https://{host}/{owner}/{repo}'
@@ -249,6 +337,36 @@ class _LifecycleBase(LifecyclePlugin):
         )
         resp.raise_for_status()
 
+    async def _archive_after_transfer(
+        self,
+        client: httpx.AsyncClient,
+        owner: str,
+        repo: str,
+    ) -> None:
+        """Archive a freshly-transferred repo, retrying the 404 window.
+
+        GitHub's transfer is async: the repo is briefly unreachable at
+        the destination owner, so the archive PATCH 404s until the
+        transfer settles.  Retry only on 404 — any other status (auth,
+        permissions, validation) is a real failure and re-raises
+        immediately.
+        """
+        for backoff in (*_TRANSFER_ARCHIVE_BACKOFFS, None):
+            try:
+                await self._set_archived(client, owner, repo, True)
+                return
+            except httpx.HTTPStatusError as exc:
+                if exc.response.status_code != 404 or backoff is None:
+                    raise
+                LOGGER.info(
+                    'Repo %s/%s not yet reachable after transfer; '
+                    'retrying archive in %ss',
+                    owner,
+                    repo,
+                    backoff,
+                )
+                await asyncio.sleep(backoff)
+
     async def _transfer(
         self,
         client: httpx.AsyncClient,

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/tests/test_deployment.py

@@ -17,6 +17,7 @@ from imbi_plugin_github.deployment import (
     GitHubDeploymentPlugin,
     GitHubEnterpriseCloudDeploymentPlugin,
     GitHubEnterpriseServerDeploymentPlugin,
+    _repo_root_from_redirect,
 )
 
 
@@ -1300,3 +1301,167 @@ class ListWorkflowsTestCase(unittest.IsolatedAsyncioTestCase):
         )
         plugin = GitHubDeploymentPlugin()
         self.assertEqual(await plugin.list_workflows(_ctx(), _CREDS), [])
+
+
+class RepoRootFromRedirectTestCase(unittest.TestCase):
+    def test_strips_subresource_to_repo_root(self) -> None:
+        self.assertEqual(
+            _repo_root_from_redirect(
+                'https://api.github.com/repositories/687046/commits'
+            ),
+            'https://api.github.com/repositories/687046',
+        )
+
+    def test_bare_repo_id(self) -> None:
+        self.assertEqual(
+            _repo_root_from_redirect(
+                'https://api.github.com/repositories/687046'
+            ),
+            'https://api.github.com/repositories/687046',
+        )
+
+    def test_returns_none_without_repositories_segment(self) -> None:
+        self.assertIsNone(
+            _repo_root_from_redirect('https://api.github.com/repos/o/r')
+        )
+
+    def test_returns_none_when_id_missing(self) -> None:
+        self.assertIsNone(
+            _repo_root_from_redirect('https://api.github.com/repositories')
+        )
+
+
+class RepoRenameRelocationTestCase(unittest.IsolatedAsyncioTestCase):
+    """A repo renamed outside Imbi: GitHub 301s the stale path to the
+    by-id form.  The client follows it (request succeeds) and reports the
+    new name on ``ctx`` so the host can self-heal the stored link.
+    """
+
+    @staticmethod
+    def _mock_rename() -> None:
+        # Stale repo-path call 301s to the canonical /repositories/{id}.
+        respx.get('https://api.github.com/repos/octo/demo/commits').mock(
+            return_value=httpx.Response(
+                301,
+                headers={
+                    'location': (
+                        'https://api.github.com/repositories/123/commits'
+                    )
+                },
+            )
+        )
+        respx.get('https://api.github.com/repositories/123/commits').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'sha': 'abc',
+                        'commit': {
+                            'message': 'msg',
+                            'author': {'name': 'X', 'date': None},
+                        },
+                    }
+                ],
+            )
+        )
+        # Head-commit CI hydration follows the same redirect.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/commits/abc/check-runs'
+        ).mock(
+            return_value=httpx.Response(
+                301,
+                headers={
+                    'location': (
+                        'https://api.github.com/repositories/123'
+                        '/commits/abc/check-runs'
+                    )
+                },
+            )
+        )
+        respx.get(
+            'https://api.github.com/repositories/123/commits/abc/check-runs'
+        ).mock(return_value=httpx.Response(200, json={'check_runs': []}))
+
+    @respx.mock
+    async def test_list_commits_follows_rename_and_reports_relocation(
+        self,
+    ) -> None:
+        self._mock_rename()
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'full_name': 'octo/renamed',
+                    'html_url': 'https://github.com/octo/renamed',
+                },
+            )
+        )
+        ctx = _ctx()
+        plugin = GitHubDeploymentPlugin()
+        commits = await plugin.list_commits(ctx, _CREDS, ref='main')
+        # The user-facing request still succeeds via the followed redirect.
+        self.assertEqual(len(commits), 1)
+        self.assertEqual(commits[0].sha, 'abc')
+        # ...and the rename is reported for the host to self-heal.
+        reloc = ctx.repository_relocation
+        assert reloc is not None
+        self.assertEqual(reloc.link_key, 'github-repository')
+        self.assertEqual(reloc.new_url, 'https://github.com/octo/renamed')
+        self.assertEqual(reloc.old_owner_repo, 'octo/demo')
+        self.assertEqual(reloc.new_owner_repo, 'octo/renamed')
+
+    @respx.mock
+    async def test_no_relocation_when_repo_not_renamed(self) -> None:
+        respx.get('https://api.github.com/repos/octo/demo/commits').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'sha': 'abc',
+                        'commit': {
+                            'message': 'msg',
+                            'author': {'name': 'X', 'date': None},
+                        },
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/commits/abc/check-runs'
+        ).mock(return_value=httpx.Response(200, json={'check_runs': []}))
+        ctx = _ctx()
+        plugin = GitHubDeploymentPlugin()
+        await plugin.list_commits(ctx, _CREDS, ref='main')
+        self.assertIsNone(ctx.repository_relocation)
+
+    @respx.mock
+    async def test_no_relocation_when_repo_root_unresolvable(self) -> None:
+        self._mock_rename()
+        # Repo-root resolution fails -> best-effort, no relocation recorded.
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(404)
+        )
+        ctx = _ctx()
+        plugin = GitHubDeploymentPlugin()
+        commits = await plugin.list_commits(ctx, _CREDS, ref='main')
+        self.assertEqual(len(commits), 1)
+        self.assertIsNone(ctx.repository_relocation)
+
+    @respx.mock
+    async def test_no_relocation_when_name_unchanged(self) -> None:
+        self._mock_rename()
+        # Redirect happened but full_name matches the stored owner/repo
+        # (e.g. a transient by-id redirect) -> nothing to heal.
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'full_name': 'octo/demo',
+                    'html_url': 'https://github.com/octo/demo',
+                },
+            )
+        )
+        ctx = _ctx()
+        plugin = GitHubDeploymentPlugin()
+        await plugin.list_commits(ctx, _CREDS, ref='main')
+        self.assertIsNone(ctx.repository_relocation)

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/tests/test_lifecycle.py

@@ -8,6 +8,7 @@ from absent links, and the 401 -> PluginAuthenticationFailed path.
 """
 
 import unittest
+import unittest.mock
 
 import httpx
 import respx
@@ -179,6 +180,127 @@ class ArchiveTestCase(unittest.IsolatedAsyncioTestCase):
             'https://github.com/octo-archive/demo',
         )
 
+    @respx.mock
+    async def test_archive_transfer_retries_settle_404(self) -> None:
+        # GitHub's transfer is async (202); the repo is briefly
+        # unreachable at the destination, so the first archive PATCH
+        # 404s.  The plugin must retry and succeed once it settles.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'demo',
+                },
+            )
+        )
+        respx.post('https://api.github.com/repos/octo/demo/transfer').mock(
+            return_value=httpx.Response(
+                202,
+                json={'name': 'demo', 'owner': {'login': 'octo-archive'}},
+            )
+        )
+        archive_route = respx.patch(
+            'https://api.github.com/repos/octo-archive/demo'
+        ).mock(
+            side_effect=[
+                httpx.Response(404, json={'message': 'Not Found'}),
+                httpx.Response(404, json={'message': 'Not Found'}),
+                httpx.Response(200, json={}),
+            ]
+        )
+
+        plugin = GitHubLifecyclePlugin()
+        with unittest.mock.patch(
+            'imbi_plugin_github.lifecycle.asyncio.sleep'
+        ) as sleep:
+            result = await plugin.on_project_archived(
+                _ctx(options={'archive_target_org': 'octo-archive'}),
+                _CREDS,
+            )
+
+        self.assertEqual(result.status, 'ok')
+        self.assertEqual(archive_route.calls.call_count, 3)
+        # Two failed attempts → two backoff sleeps before success.
+        self.assertEqual(sleep.await_count, 2)
+
+    @respx.mock
+    async def test_archive_transfer_exhausts_retries_on_persistent_404(
+        self,
+    ) -> None:
+        # If the transfer never settles within the retry budget the
+        # final 404 must propagate so the dispatcher records a failure.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'demo',
+                },
+            )
+        )
+        respx.post('https://api.github.com/repos/octo/demo/transfer').mock(
+            return_value=httpx.Response(
+                202,
+                json={'name': 'demo', 'owner': {'login': 'octo-archive'}},
+            )
+        )
+        archive_route = respx.patch(
+            'https://api.github.com/repos/octo-archive/demo'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+
+        plugin = GitHubLifecyclePlugin()
+        with unittest.mock.patch(
+            'imbi_plugin_github.lifecycle.asyncio.sleep'
+        ) as sleep:
+            with self.assertRaises(httpx.HTTPStatusError):
+                await plugin.on_project_archived(
+                    _ctx(options={'archive_target_org': 'octo-archive'}),
+                    _CREDS,
+                )
+
+        # Three backoffs configured → four total attempts.
+        self.assertEqual(archive_route.calls.call_count, 4)
+        self.assertEqual(sleep.await_count, 3)
+
+    @respx.mock
+    async def test_archive_transfer_does_not_retry_non_404(self) -> None:
+        # A non-404 (e.g. permissions) is a real failure: raise at once.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'demo',
+                },
+            )
+        )
+        respx.post('https://api.github.com/repos/octo/demo/transfer').mock(
+            return_value=httpx.Response(
+                202,
+                json={'name': 'demo', 'owner': {'login': 'octo-archive'}},
+            )
+        )
+        archive_route = respx.patch(
+            'https://api.github.com/repos/octo-archive/demo'
+        ).mock(return_value=httpx.Response(403, json={'message': 'Forbidden'}))
+
+        plugin = GitHubLifecyclePlugin()
+        with unittest.mock.patch(
+            'imbi_plugin_github.lifecycle.asyncio.sleep'
+        ) as sleep:
+            with self.assertRaises(httpx.HTTPStatusError):
+                await plugin.on_project_archived(
+                    _ctx(options={'archive_target_org': 'octo-archive'}),
+                    _CREDS,
+                )
+
+        self.assertEqual(archive_route.calls.call_count, 1)
+        self.assertEqual(sleep.await_count, 0)
+
     @respx.mock
     async def test_archive_transfer_when_already_archived(self) -> None:
         # GitHub forbids transferring archived repos, so the plugin must
@@ -435,3 +557,179 @@ class GhecApiBaseTestCase(unittest.IsolatedAsyncioTestCase):
             result.artifacts['repo_url'],
             'https://tenant.ghe.com/octo/demo',
         )
+
+
+class RenameRelocationTestCase(unittest.IsolatedAsyncioTestCase):
+    """A repo renamed outside Imbi: the stale path 301s to the by-id form,
+    the client follows it, and the canonical owner/repo are adopted and
+    reported on ``ctx`` for the host to self-heal the link.
+    """
+
+    @respx.mock
+    async def test_archive_follows_rename_and_reports_relocation(
+        self,
+    ) -> None:
+        # Stale path 301s to the canonical /repositories/{id}; the repo's
+        # current name is ``renamed``.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                301,
+                headers={
+                    'location': 'https://api.github.com/repositories/123'
+                },
+            )
+        )
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'renamed',
+                    'html_url': 'https://github.com/octo/renamed',
+                },
+            )
+        )
+        # Archive targets the canonical name we adopted from the payload.
+        patch_route = respx.patch(
+            'https://api.github.com/repos/octo/renamed'
+        ).mock(return_value=httpx.Response(200, json={}))
+
+        ctx = _ctx()
+        plugin = GitHubLifecyclePlugin()
+        result = await plugin.on_project_archived(ctx, _CREDS)
+
+        self.assertEqual(result.status, 'ok')
+        self.assertEqual(patch_route.calls.call_count, 1)
+        self.assertEqual(
+            result.artifacts['repo_url'], 'https://github.com/octo/renamed'
+        )
+        reloc = ctx.repository_relocation
+        assert reloc is not None
+        self.assertEqual(reloc.link_key, 'github-repository')
+        self.assertEqual(reloc.new_url, 'https://github.com/octo/renamed')
+        self.assertEqual(reloc.old_owner_repo, 'octo/demo')
+        self.assertEqual(reloc.new_owner_repo, 'octo/renamed')
+
+    @respx.mock
+    async def test_unarchive_follows_rename_and_reports_relocation(
+        self,
+    ) -> None:
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                301,
+                headers={
+                    'location': 'https://api.github.com/repositories/123'
+                },
+            )
+        )
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': True,
+                    'owner': {'login': 'octo'},
+                    'name': 'renamed',
+                    'html_url': 'https://github.com/octo/renamed',
+                },
+            )
+        )
+        patch_route = respx.patch(
+            'https://api.github.com/repos/octo/renamed'
+        ).mock(return_value=httpx.Response(200, json={}))
+
+        ctx = _ctx()
+        plugin = GitHubLifecyclePlugin()
+        result = await plugin.on_project_unarchived(ctx, _CREDS)
+
+        self.assertEqual(result.status, 'ok')
+        self.assertEqual(patch_route.calls.call_count, 1)
+        reloc = ctx.repository_relocation
+        assert reloc is not None
+        self.assertEqual(reloc.new_owner_repo, 'octo/renamed')
+
+    @respx.mock
+    async def test_archive_skip_uses_canonical_owner_in_artifact(
+        self,
+    ) -> None:
+        # External rename moved the repo to a new owner *and* it is already
+        # archived, so we hit the skip path. The artifact URL must reflect
+        # the canonical owner/repo, not the stale link-derived owner.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                301,
+                headers={
+                    'location': 'https://api.github.com/repositories/123'
+                },
+            )
+        )
+        respx.get('https://api.github.com/repositories/123').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': True,
+                    'owner': {'login': 'octo-new'},
+                    'name': 'renamed',
+                    'html_url': 'https://github.com/octo-new/renamed',
+                },
+            )
+        )
+
+        ctx = _ctx()
+        plugin = GitHubLifecyclePlugin()
+        result = await plugin.on_project_archived(ctx, _CREDS)
+
+        self.assertEqual(result.status, 'skipped')
+        self.assertEqual(
+            result.artifacts['repo_url'],
+            'https://github.com/octo-new/renamed',
+        )
+
+    @respx.mock
+    async def test_no_relocation_when_not_renamed(self) -> None:
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'demo',
+                },
+            )
+        )
+        respx.patch('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(200, json={})
+        )
+        ctx = _ctx()
+        plugin = GitHubLifecyclePlugin()
+        await plugin.on_project_archived(ctx, _CREDS)
+        self.assertIsNone(ctx.repository_relocation)
+
+    @respx.mock
+    async def test_intentional_transfer_is_not_reported_as_relocation(
+        self,
+    ) -> None:
+        # Repo is found at its stored location (no external rename), then
+        # we transfer it to the archive org. That intentional move must
+        # NOT be reported as a relocation.
+        respx.get('https://api.github.com/repos/octo/demo').mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'archived': False,
+                    'owner': {'login': 'octo'},
+                    'name': 'demo',
+                },
+            )
+        )
+        respx.post('https://api.github.com/repos/octo/demo/transfer').mock(
+            return_value=httpx.Response(202, json={'name': 'demo'})
+        )
+        respx.patch('https://api.github.com/repos/archives/demo').mock(
+            return_value=httpx.Response(200, json={})
+        )
+        ctx = _ctx(options={'archive_target_org': 'archives'})
+        plugin = GitHubLifecyclePlugin()
+        result = await plugin.on_project_archived(ctx, _CREDS)
+        self.assertEqual(result.status, 'ok')
+        self.assertIsNone(ctx.repository_relocation)

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.5.0}/uv.lock

@@ -2,6 +2,21 @@ version = 1
 revision = 3
 requires-python = ">=3.14"
 
+[options]
+exclude-newer = "0001-01-01T00:00:00Z"  # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
+exclude-newer-span = "P7D"
+
+[options.exclude-newer-package]
+imbi-common = false
+imbi-plugin-pagerduty = false
+imbi-plugin-github = false
+imbi-plugin-logzio = false
+imbi-plugin-aws = false
+imbi-plugin-sonarqube = false
+clickhouse-connect = false
+imbi-plugin-sentry = false
+imbi-plugin-oidc = false
+
 [[package]]
 name = "aiohappyeyeballs"
 version = "2.6.1"
@@ -652,7 +667,7 @@ wheels = [
 
 [[package]]
 name = "imbi-common"
-version = "2.5.5"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
   { name = "cryptography" },
@@ -668,9 +683,9 @@ dependencies = [
   { name = "python-slugify" },
   { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0d/b7/6dab7155b281f9c075d3434e3f234ef217fe49db840b14e59e3e5a75faa2/imbi_common-2.5.5.tar.gz", hash = "sha256:56751efe31fdc1fcb1d1be19e6b3f073d5b3e4fda3c89c0bcdec5c7943549477", size = 277481, upload-time = "2026-05-20T02:10:09.044Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/4b/b0/5f28ac0670d239c885822e5a7c9a94b2bb9c1ea205dccba82ac2ae36f329/imbi_common-2.7.0.tar.gz", hash = "sha256:723d2a7ecffef3f0cf86828173586a9721931b95068718c7b0c7cff768c7f764", size = 303583, upload-time = "2026-05-28T12:56:17.525Z" }
 wheels = [
-  { url = "https://files.pythonhosted.org/packages/48/04/69e72ec3a1968a9dd8b91df38e6a7be16e1399a054a953777a23f34c60ca/imbi_common-2.5.5-py3-none-any.whl", hash = "sha256:19ffa23d9cdb0b8065af1d3a9166f819c15414fc4b5707d089adaf64b932ebf1", size = 91154, upload-time = "2026-05-20T02:10:07.448Z" },
+  { url = "https://files.pythonhosted.org/packages/ce/33/e801c0e9d7ecfef434ca1f178291584f4dce1e55f34590c9425c2086c4f6/imbi_common-2.7.0-py3-none-any.whl", hash = "sha256:c475153119376753d5f09b18de686eb872464625fdaf073aa893fec38b3956ab", size = 98903, upload-time = "2026-05-28T12:56:16.147Z" },
 ]
 
 [package.optional-dependencies]
@@ -688,7 +703,7 @@ server = [
 
 [[package]]
 name = "imbi-plugin-github"
-version = "1.2.0"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
   { name = "httpx" },
@@ -716,7 +731,7 @@ dist = [
 [package.metadata]
 requires-dist = [
   { name = "httpx", specifier = ">=0.27" },
-  { name = "imbi-common", specifier = ">=2.5.5" },
+  { name = "imbi-common", specifier = ">=2.7.0" },
   { name = "pydantic", specifier = ">=2" },
 ]