imbi-plugin-github 2.20.0__tar.gz → 2.21.1__tar.gz

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbi-plugin-github
-Version: 2.20.0
+Version: 2.21.1
 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.20.0
+Requires-Dist: imbi-common[databases]==2.21.1
 Requires-Dist: pydantic>=2
 Requires-Dist: pyjwt[crypto]>=2.8
 Description-Content-Type: text/markdown

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "2.20.0"
+version = "2.21.1"
 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.20.0",
+  "imbi-common[databases]==2.21.1",
   "pydantic>=2",
   "pyjwt[crypto]>=2.8",
 ]

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/src/imbi/plugins/github/README.md

@@ -109,6 +109,7 @@ Scoped to one capability and delivered on
 | `lifecycle` | `archive_target_org` | Org to transfer repos to before archiving; blank archives in place.                     |
 | `lifecycle` | `create_org`         | Default org for repo creation when no `org_mapping` entry matches.                       |
 | `lifecycle` | `org_mapping`        | Per-project-type-slug org overrides; the first match wins over `create_org`.             |
+| `lifecycle` | `create_visibility`  | Visibility for created repos: `private`, `internal`, or `public`. Blank follows the flavor — `internal` for `ghec`/`ghes`, `public` for `github`. |
 
 ## Credentials
 

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/src/imbi/plugins/github/deployment.py

@@ -46,6 +46,7 @@ from imbi.common.plugins.base import (
     RefInfo,
     ReleaseInfo,
     RemoteDeployment,
+    RemoteRelease,
     WorkflowFile,
 )
 from imbi.common.plugins.errors import PluginAuthenticationFailed
@@ -1196,19 +1197,19 @@ class GitHubDeployment(DeploymentCapability):
         run_cache[run_id] = result
         return result
 
-    async def _release_notes_for_ref(
+    async def _release_for_ref(
         self, client: httpx.AsyncClient, ref: str
-    ) -> str | None:
-        """Return the GitHub release notes body for a deployed ref.
-
-        A deployment created against a semver tag has a matching GitHub
-        release whose ``body`` is the "What's Changed" markdown the host
-        persists on the ``Release`` node.  Refs that aren't a release tag
-        (branches, raw SHAs) 404 here and yield ``None`` -- resync is
-        never blocked by a missing or unreadable release.  A ``403``
-        (token lacks scope to read releases) is cached process-wide so a
-        forbidden token short-circuits instead of re-issuing the request
-        for every deployment on every resync sweep.
+    ) -> RemoteRelease | None:
+        """Return the GitHub release for ``ref``, metadata included.
+
+        The single release lookup every caller degrades through: a 404 /
+        non-200 / parse failure yields ``None``, and a ``403`` (token lacks
+        scope to read releases) is cached process-wide so a forbidden token
+        short-circuits instead of re-issuing the request for every
+        deployment on every resync sweep.  ``author`` is the login GitHub
+        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.
         """
         if _releases_forbidden(client):
             return None
@@ -1227,8 +1228,46 @@ class GitHubDeployment(DeploymentCapability):
             data = typing.cast(dict[str, typing.Any], resp.json())
         except ValueError:
             return None
+        author: dict[str, typing.Any] = data.get('author') or {}
+        login = author.get('login')
+        subject = author.get('id')
         body = data.get('body')
-        return str(body) if body else None
+        name = data.get('name')
+        html_url = data.get('html_url')
+        return RemoteRelease(
+            tag=ref,
+            name=str(name) if name else None,
+            body_markdown=str(body) if body else None,
+            author=str(login) if login else None,
+            author_subject=str(subject) if subject is not None else None,
+            html_url=str(html_url) if html_url else None,
+            published_at=_parse_iso(data.get('published_at')),
+        )
+
+    async def get_release(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        tag: str,
+    ) -> RemoteRelease | None:
+        """Return the GitHub release for ``tag`` with its author."""
+        async with self._client(ctx, credentials) as client:
+            return await self._release_for_ref(client, tag)
+
+    async def _release_notes_for_ref(
+        self, client: httpx.AsyncClient, ref: str
+    ) -> str | None:
+        """Return the GitHub release notes body for a deployed ref.
+
+        A deployment created against a semver tag has a matching GitHub
+        release whose ``body`` is the "What's Changed" markdown the host
+        persists on the ``Release`` node.  Refs that aren't a release tag
+        (branches, raw SHAs) 404 in :meth:`_release_for_ref` and yield
+        ``None`` -- resync is never blocked by a missing or unreadable
+        release.
+        """
+        release = await self._release_for_ref(client, ref)
+        return release.body_markdown if release else None
 
     async def _latest_status(
         self, client: httpx.AsyncClient, deployment_id: str

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/src/imbi/plugins/github/lifecycle.py

@@ -75,6 +75,39 @@ _HTTP_TIMEOUT_SECONDS = 10.0
 # hanging the operator's archive request.
 _TRANSFER_ARCHIVE_BACKOFFS: tuple[float, ...] = (0.5, 1.0, 2.0)
 
+# Visibilities accepted by the ``create_visibility`` option.  ``internal``
+# is only meaningful on a GHEC tenant or GHES appliance.
+_VISIBILITIES = frozenset({'private', 'internal', 'public'})
+
+
+def _error_detail(response: httpx.Response) -> str:
+    """Flatten a GitHub error body into one operator-facing string.
+
+    Keeps the top-level ``message`` and each entry of the ``errors``
+    array (``field: message``) so a validation failure names the field
+    that GitHub rejected.
+    """
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if not isinstance(body, dict):
+        return f'HTTP {response.status_code}: {response.text[:200]}'
+    payload = typing.cast(dict[str, object], body)
+    parts = [str(payload.get('message') or f'HTTP {response.status_code}')]
+    errors = payload.get('errors')
+    if isinstance(errors, list):
+        for item in typing.cast(list[object], errors):
+            if not isinstance(item, dict):
+                continue
+            entry = typing.cast(dict[str, object], item)
+            text = entry.get('message') or entry.get('code')
+            if not text:
+                continue
+            field = entry.get('field')
+            parts.append(f'{field}: {text}' if field else str(text))
+    return ' - '.join(parts)
+
 
 async def _raise_on_401(response: httpx.Response) -> None:
     """Convert a 401 from GitHub into :class:`PluginAuthenticationFailed`.
@@ -144,6 +177,35 @@ class GitHubLifecycle(LifecycleCapability):
             return raw.strip()
         return None
 
+    @staticmethod
+    def _default_visibility(ctx: PluginContext) -> str:
+        """Pick the create visibility when the option is unset.
+
+        The right default differs per host, so it can't be a manifest
+        constant: enterprise hosts (a GHEC tenant or a GHES appliance)
+        get ``internal`` -- readable across the enterprise, and the only
+        useful non-public choice on orgs that forbid public repos --
+        while github.com has no ``internal`` visibility at all and gets
+        ``public``.  Never *silently* narrower than that on enterprise
+        and never wider on github.com; operators who want something
+        else set ``create_visibility`` explicitly.
+        """
+        flavor = str(ctx.integration_options.get('flavor') or '').strip()
+        return 'public' if flavor == 'github' else 'internal'
+
+    def _resolve_visibility(self, ctx: PluginContext) -> str:
+        """Resolve the visibility new repos are created with.
+
+        An explicit ``create_visibility`` option wins; anything unset or
+        unrecognized falls back to the host-appropriate default rather
+        than inheriting GitHub's create API default of *public*, which
+        an enterprise org that forbids public repos rejects with a 422.
+        """
+        raw = ctx.capability_options.get('create_visibility')
+        if isinstance(raw, str) and raw.strip().lower() in _VISIBILITIES:
+            return raw.strip().lower()
+        return self._default_visibility(ctx)
+
     @staticmethod
     def _resolve_create_org(ctx: PluginContext) -> str | None:
         """Resolve the GitHub org for create / relocate from plugin options.
@@ -616,15 +678,31 @@ class GitHubLifecycle(LifecycleCapability):
         org: str,
         ctx: PluginContext,
     ) -> dict[str, typing.Any]:
+        visibility = self._resolve_visibility(ctx)
         resp = await client.post(
             f'/orgs/{org}/repos',
             json={
                 'name': ctx.project_slug,
                 'description': ctx.project_description or '',
                 'homepage': ctx.project_ui_url or '',
+                # ``visibility`` is authoritative where it's supported;
+                # ``private`` rides along so a host that only honors the
+                # older field degrades to private instead of silently
+                # creating a public repo.
+                'visibility': visibility,
+                'private': visibility != 'public',
             },
         )
-        resp.raise_for_status()
+        try:
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            # ``raise_for_status`` reports only the status line, hiding
+            # the ``message``/``errors`` body that says *why* -- e.g. an
+            # org whose policy forbids the requested visibility.
+            raise RuntimeError(
+                f'GitHub refused to create {org}/{ctx.project_slug} with '
+                f'visibility={visibility}: {_error_detail(exc.response)}'
+            ) from exc
         return typing.cast(dict[str, typing.Any], resp.json())
 
     async def _patch_repo_attrs(

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/src/imbi/plugins/github/plugin.py

@@ -174,6 +174,21 @@ _LIFECYCLE_OPTIONS: list[PluginOption] = [
         type='string',
         required=False,
     ),
+    PluginOption(
+        name='create_visibility',
+        label='Visibility for created repos',
+        description=(
+            'Visibility applied to repos created by project creation.  '
+            'Leave blank to follow the Integration flavor: ``internal`` '
+            'on a GHEC tenant or GHES appliance, ``public`` on '
+            'github.com, which has no internal visibility.  Set a value '
+            'to override -- note that an org forbidding public repos '
+            'rejects ``public`` with a 422.'
+        ),
+        type='string',
+        choices=['private', 'internal', 'public'],
+        required=False,
+    ),
     PluginOption(
         name='org_mapping',
         label='Project-type to org overrides',

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/tests/test_deployment.py

@@ -1555,6 +1555,66 @@ class GetReleaseNotesTestCase(unittest.IsolatedAsyncioTestCase):
         notes = await plugin.get_release_notes(_ctx(), _CREDS, '9.9.9')
         self.assertIsNone(notes)
 
+    @respx.mock
+    async def test_get_release_carries_the_remote_author(self) -> None:
+        # Attribution comes from GitHub: the login it credits with the
+        # release, plus the numeric id the host resolves to an Imbi user.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/3.23.4'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'tag_name': '3.23.4',
+                    'name': 'Release 3.23.4',
+                    'body': '## Fixed\n- the thing',
+                    'html_url': 'https://github.com/octo/demo/releases/3.23.4',
+                    'published_at': '2026-07-29T12:00:00Z',
+                    'author': {'login': 'octocat', 'id': 583231},
+                },
+            )
+        )
+        plugin = GitHubDeployment()
+        release = await plugin.get_release(_ctx(), _CREDS, '3.23.4')
+        assert release is not None
+        self.assertEqual('octocat', release.author)
+        self.assertEqual('583231', release.author_subject)
+        self.assertEqual('Release 3.23.4', release.name)
+        self.assertEqual('## Fixed\n- the thing', release.body_markdown)
+        self.assertEqual(
+            'https://github.com/octo/demo/releases/3.23.4', release.html_url
+        )
+        self.assertEqual(
+            datetime.datetime(2026, 7, 29, 12, 0, tzinfo=datetime.UTC),
+            release.published_at,
+        )
+
+    @respx.mock
+    async def test_get_release_returns_none_when_no_release(self) -> None:
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/9.9.9'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        plugin = GitHubDeployment()
+        self.assertIsNone(await plugin.get_release(_ctx(), _CREDS, '9.9.9'))
+
+    @respx.mock
+    async def test_get_release_tolerates_a_missing_author(self) -> None:
+        # A release with no author (a tag-only release, or a deleted
+        # account) still yields its body rather than failing the lookup.
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/1.0.0'
+        ).mock(
+            return_value=httpx.Response(
+                200, json={'tag_name': '1.0.0', 'body': 'notes'}
+            )
+        )
+        plugin = GitHubDeployment()
+        release = await plugin.get_release(_ctx(), _CREDS, '1.0.0')
+        assert release is not None
+        self.assertIsNone(release.author)
+        self.assertIsNone(release.author_subject)
+        self.assertEqual('notes', release.body_markdown)
+
 
 class CheckStatusTestCase(unittest.IsolatedAsyncioTestCase):
     @respx.mock

{imbi_plugin_github-2.20.0 → imbi_plugin_github-2.21.1}/tests/test_lifecycle.py

@@ -7,6 +7,7 @@ archived repo, the rename-on-transfer case, repo-resolution failure
 from absent links, and the 401 -> PluginAuthenticationFailed path.
 """
 
+import json
 import unittest
 import unittest.mock
 
@@ -98,6 +99,18 @@ class ManifestTestCase(unittest.TestCase):
         self.assertIn('org_mapping', opts)
         self.assertEqual(opts['org_mapping'].type, 'mapping')
 
+    def test_create_visibility_option_has_no_manifest_default(self) -> None:
+        # The default is flavor-dependent, so it must be resolved by the
+        # handler -- a manifest default gets pre-filled into the stored
+        # options by the admin wizard and would defeat that.
+        opts = {opt.name: opt for opt in _lifecycle_cap().options}
+        self.assertIn('create_visibility', opts)
+        self.assertIsNone(opts['create_visibility'].default)
+        self.assertEqual(
+            opts['create_visibility'].choices,
+            ['private', 'internal', 'public'],
+        )
+
     def test_no_host_option(self) -> None:
         # Host now comes from the Integration's flavor/host options, not a
         # per-capability option on the lifecycle capability itself.
@@ -826,9 +839,16 @@ class CreateTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(result.status, 'ok')
         self.assertEqual(create_route.calls.call_count, 1)
         self.assertEqual(
-            create_route.calls.last.request.read(),
-            b'{"name":"demo","description":"An example API",'
-            b'"homepage":"https://imbi.example.com/projects/p"}',
+            json.loads(create_route.calls.last.request.read()),
+            {
+                'name': 'demo',
+                'description': 'An example API',
+                'homepage': 'https://imbi.example.com/projects/p',
+                # ``github`` flavor, no option set -> public, the only
+                # visibility github.com shares with the enterprise hosts.
+                'visibility': 'public',
+                'private': False,
+            },
         )
         self.assertIsNotNone(ctx.link_writeback)
         assert ctx.link_writeback is not None
@@ -867,6 +887,126 @@ class CreateTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(result.status, 'ok')
         self.assertEqual(create_route.calls.call_count, 1)
 
+    @respx.mock
+    async def test_create_honors_configured_visibility(self) -> None:
+        respx.get('https://api.github.com/repos/aweber-apis/demo').mock(
+            return_value=httpx.Response(404, json={'message': 'Not Found'})
+        )
+        create_route = respx.post(
+            'https://api.github.com/orgs/aweber-apis/repos'
+        ).mock(
+            return_value=httpx.Response(
+                201,
+                json={
+                    'name': 'demo',
+                    'html_url': 'https://github.com/aweber-apis/demo',
+                },
+            )
+        )
+        ctx = _ctx(
+            options={
+                'org_mapping': {'api-service': 'aweber-apis'},
+                'create_visibility': 'private',
+            },
+            project_links={},
+            project_type_slugs=['api-service'],
+        )
+        plugin = GitHubLifecycle()
+        result = await plugin.on_project_created(ctx, _CREDS)
+
+        self.assertEqual(result.status, 'ok')
+        body = json.loads(create_route.calls.last.request.read())
+        # The option overrides the ``internal`` default.
+        self.assertEqual(body['visibility'], 'private')
+        self.assertIs(body['private'], True)
+
+    async def _create_on(
+        self, flavor: str, host: str, api_base: str
+    ) -> dict[str, object]:
+        """Run a create against one flavor, returning the POST body."""
+        respx.get(f'{api_base}/repos/aweber-apis/demo').mock(
+            return_value=httpx.Response(404, json={'message': 'Not Found'})
+        )
+        create_route = respx.post(f'{api_base}/orgs/aweber-apis/repos').mock(
+            return_value=httpx.Response(
+                201,
+                json={
+                    'name': 'demo',
+                    'html_url': f'https://{host}/aweber-apis/demo',
+                },
+            )
+        )
+        ctx = _ctx(
+            options={'org_mapping': {'api-service': 'aweber-apis'}},
+            project_links={},
+            project_type_slugs=['api-service'],
+            connection=_connection(flavor, host),
+        )
+        result = await GitHubLifecycle().on_project_created(ctx, _CREDS)
+        self.assertEqual(result.status, 'ok')
+        body: dict[str, object] = json.loads(
+            create_route.calls.last.request.read()
+        )
+        return body
+
+    @respx.mock
+    async def test_create_defaults_to_internal_on_ghec(self) -> None:
+        # An unset option on an enterprise host means ``internal``, not
+        # the ``public`` default that github.com gets.
+        body = await self._create_on(
+            'ghec', 'tenant.ghe.com', 'https://api.tenant.ghe.com'
+        )
+        self.assertEqual(body['visibility'], 'internal')
+        self.assertIs(body['private'], True)
+
+    @respx.mock
+    async def test_create_defaults_to_internal_on_ghes(self) -> None:
+        body = await self._create_on(
+            'ghes', 'github.example.com', 'https://github.example.com/api/v3'
+        )
+        self.assertEqual(body['visibility'], 'internal')
+        self.assertIs(body['private'], True)
+
+    @respx.mock
+    async def test_create_surfaces_github_validation_detail(self) -> None:
+        # A 422 from GitHub (e.g. org policy forbids the visibility) must
+        # name the reason -- ``raise_for_status`` alone hides the body.
+        respx.get('https://api.github.com/repos/aweber-apis/demo').mock(
+            return_value=httpx.Response(404, json={'message': 'Not Found'})
+        )
+        respx.post('https://api.github.com/orgs/aweber-apis/repos').mock(
+            return_value=httpx.Response(
+                422,
+                json={
+                    'message': 'Repository creation failed.',
+                    'errors': [
+                        {
+                            'resource': 'Repository',
+                            'field': 'visibility',
+                            'message': "Visibility can't be public",
+                        }
+                    ],
+                },
+            )
+        )
+        ctx = _ctx(
+            options={
+                'org_mapping': {'api-service': 'aweber-apis'},
+                'create_visibility': 'public',
+            },
+            project_links={},
+            project_type_slugs=['api-service'],
+        )
+        plugin = GitHubLifecycle()
+        with self.assertRaises(RuntimeError) as raised:
+            await plugin.on_project_created(ctx, _CREDS)
+
+        message = str(raised.exception)
+        self.assertIn('aweber-apis/demo', message)
+        self.assertIn('visibility=public', message)
+        self.assertIn('Repository creation failed.', message)
+        self.assertIn("visibility: Visibility can't be public", message)
+
     async def test_create_skips_when_no_target_org_configured(self) -> None:
         # Neither mapping nor template -> clean skip rather than HTTP.
         ctx = _ctx(