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

imbi_plugin_github-1.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbi-plugin-github
-Version: 1.3.0
+Version: 1.4.0
 Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
 Author-email: "Gavin M. Roy" <gavinr@aweber.com>
 License: BSD-3-Clause
@@ -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.4.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.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "1.3.0"
+version = "1.4.0"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -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.4.0}/src/imbi_plugin_github/deployment.py

@@ -580,7 +580,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.4.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.4.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
 
@@ -56,6 +67,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`.
@@ -172,8 +190,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',
@@ -249,6 +270,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.4.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

{imbi_plugin_github-1.3.0 → imbi_plugin_github-1.4.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"
@@ -688,7 +703,7 @@ server = [
 
 [[package]]
 name = "imbi-plugin-github"
-version = "1.2.0"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
   { name = "httpx" },