imbi-plugin-github 2.17.0__tar.gz → 2.19.0__tar.gz

imbi_plugin_github-2.19.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: imbi-plugin-github
+Version: 2.19.0
+Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+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.19.0
+Requires-Dist: pydantic>=2
+Requires-Dist: pyjwt[crypto]>=2.8
+Description-Content-Type: text/markdown
+
+# imbi-plugin-github
+
+GitHub plugin for Imbi. A single plugin — slug **`github`** — backs every
+GitHub Integration; the integration-level `flavor` option selects
+github.com (`github`), GitHub Enterprise Cloud (`ghec`), or GitHub
+Enterprise Server (`ghes`), and `host` names the tenant or appliance.
+
+## Capabilities
+
+| Kind              | Handler                   |
+| ----------------- | ------------------------- |
+| `identity`        | `GitHubIdentity`          |
+| `deployment`      | `GitHubDeployment`        |
+| `lifecycle`       | `GitHubLifecycle`         |
+| `webhook-actions` | `GitHubWebhookActions`    |
+| `commit-sync`     | `GitHubCommitSync`        |
+| `pr-sync`         | `GitHubPullRequestSync`   |
+| `analysis`        | `GitHubDoctor`            |
+
+### Identity
+
+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
+
+Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
+plus tag and release creation. Promote behaviour is inferred from the
+ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
++ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
+`env_payloads` and arrive on `PluginContext.environment_config`.
+
+### Lifecycle
+
+Reacts to project archive / unarchive by archiving the matching repo via
+`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
+`archive_target_org` option is set, archive **also** transfers the repo to
+that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
+moving sunset projects into a dedicated "archive" org so they no longer
+crowd primary-org searches.
+
+GitHub refuses to transfer archived repos, so an already-archived source
+is briefly unarchived, transferred, and re-archived at the destination.
+On unarchive the plugin only flips `archived` back to `false` at the
+repo's current location — it does **not** transfer back to the original
+org.
+
+Archiving requires admin scope on the repo; transferring additionally
+requires admin permission on the target organization.
+
+### Webhook actions (commit / tag / PR sync)
+
+The `webhook-actions` capability exposes the actions the gateway
+dispatches from webhook deliveries. A `WebhookRule.handler` is
+`"<plugin_slug>#<action_name>"`, and the slug is the **plugin** slug —
+`github` — not the capability kind:
+
+| Action                | Handler                      | Records into ClickHouse |
+| --------------------- | ---------------------------- | ----------------------- |
+| `sync_commits`        | `github#sync_commits`        | `commits`               |
+| `sync_tags`           | `github#sync_tags`           | `tags`                  |
+| `sync_pull_requests`  | `github#sync_pull_requests`  | `pull_requests`         |
+
+`sync_commits` and `sync_tags` are dispatched from `push` deliveries;
+`sync_pull_requests` from `pull_request` deliveries.
+
+`sync_commits` fetches the full set of commits in a push via the compare
+API (paginated, so it isn't capped by the 20-commit inline payload limit);
+`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
+full tag list. Branch/tag gating is the rule's CEL `filter_expression`,
+which evaluates against the recorded event — the webhook body is under
+`payload` (e.g. `payload.ref == "refs/heads/main"`,
+`payload.ref.startsWith("refs/tags/")`). The API
+flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
+`api_base_url`, else a connected GitHub plugin on the same service, else
+the service endpoint, else the payload's `repository.url`.
+
+Unlike identity/deployment/lifecycle (which act as the OAuth user),
+commit-sync runs without an actor and authenticates with a **service**
+credential in one of two modes, resolved per call:
+
+- **PAT** — a static `access_token`.
+- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
+  and mints a short-lived **installation token** (cached process-wide
+  until shortly before it expires), so no static, expiring token is
+  stored. `installation_id` is optional — when unset it is discovered
+  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
+  The App needs **Contents: Read-only**.
+
+## Integration options
+
+Asked once per Integration and delivered to every capability on
+`PluginContext.integration_options`:
+
+| Option   | Required  | Description                                                             |
+| -------- | --------- | ----------------------------------------------------------------------- |
+| `flavor` | yes       | `github`, `ghec`, or `ghes`.                                            |
+| `host`   | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`). |
+
+## Capability options
+
+Scoped to one capability and delivered on
+`PluginContext.capability_options`:
+
+| Capability  | Option               | Description                                                                             |
+| ----------- | -------------------- | --------------------------------------------------------------------------------------- |
+| `identity`  | `default_scopes`     | Space-separated OAuth scopes (default: `read:user user:email repo workflow`).            |
+| `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`.             |
+
+## Credentials
+
+One credential store per Integration — every capability receives the
+same decrypted blob. All fields are individually optional and validated
+per call, so an identity-only or App-only Integration is valid:
+
+| Field             | Used by            | Description                                       |
+| ----------------- | ------------------ | ------------------------------------------------- |
+| `access_token`    | service (PAT mode) | Static personal/service token.                    |
+| `app_id`          | service (App mode) | GitHub App identifier.                            |
+| `private_key`     | service (App mode) | App private key — raw PEM or base64-encoded PEM.  |
+| `installation_id` | service (App mode) | Optional; discovered from the repo when unset.    |
+| `client_id`       | `identity`         | OAuth App client id.                              |
+| `client_secret`   | `identity`         | OAuth App client secret.                          |
+
+For `commit-sync`, `pr-sync`, and `deployment` provide **either**
+`access_token` **or** `app_id` + `private_key`. `lifecycle` acts as the
+user and takes only `access_token` (or `token`) — it does not fall back
+to GitHub App credentials.
+
+## License
+
+BSD-3-Clause.

imbi_plugin_github-2.19.0/README.md

@@ -0,0 +1,135 @@
+# imbi-plugin-github
+
+GitHub plugin for Imbi. A single plugin — slug **`github`** — backs every
+GitHub Integration; the integration-level `flavor` option selects
+github.com (`github`), GitHub Enterprise Cloud (`ghec`), or GitHub
+Enterprise Server (`ghes`), and `host` names the tenant or appliance.
+
+## Capabilities
+
+| Kind              | Handler                   |
+| ----------------- | ------------------------- |
+| `identity`        | `GitHubIdentity`          |
+| `deployment`      | `GitHubDeployment`        |
+| `lifecycle`       | `GitHubLifecycle`         |
+| `webhook-actions` | `GitHubWebhookActions`    |
+| `commit-sync`     | `GitHubCommitSync`        |
+| `pr-sync`         | `GitHubPullRequestSync`   |
+| `analysis`        | `GitHubDoctor`            |
+
+### Identity
+
+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
+
+Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
+plus tag and release creation. Promote behaviour is inferred from the
+ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
++ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
+`env_payloads` and arrive on `PluginContext.environment_config`.
+
+### Lifecycle
+
+Reacts to project archive / unarchive by archiving the matching repo via
+`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
+`archive_target_org` option is set, archive **also** transfers the repo to
+that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
+moving sunset projects into a dedicated "archive" org so they no longer
+crowd primary-org searches.
+
+GitHub refuses to transfer archived repos, so an already-archived source
+is briefly unarchived, transferred, and re-archived at the destination.
+On unarchive the plugin only flips `archived` back to `false` at the
+repo's current location — it does **not** transfer back to the original
+org.
+
+Archiving requires admin scope on the repo; transferring additionally
+requires admin permission on the target organization.
+
+### Webhook actions (commit / tag / PR sync)
+
+The `webhook-actions` capability exposes the actions the gateway
+dispatches from webhook deliveries. A `WebhookRule.handler` is
+`"<plugin_slug>#<action_name>"`, and the slug is the **plugin** slug —
+`github` — not the capability kind:
+
+| Action                | Handler                      | Records into ClickHouse |
+| --------------------- | ---------------------------- | ----------------------- |
+| `sync_commits`        | `github#sync_commits`        | `commits`               |
+| `sync_tags`           | `github#sync_tags`           | `tags`                  |
+| `sync_pull_requests`  | `github#sync_pull_requests`  | `pull_requests`         |
+
+`sync_commits` and `sync_tags` are dispatched from `push` deliveries;
+`sync_pull_requests` from `pull_request` deliveries.
+
+`sync_commits` fetches the full set of commits in a push via the compare
+API (paginated, so it isn't capped by the 20-commit inline payload limit);
+`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
+full tag list. Branch/tag gating is the rule's CEL `filter_expression`,
+which evaluates against the recorded event — the webhook body is under
+`payload` (e.g. `payload.ref == "refs/heads/main"`,
+`payload.ref.startsWith("refs/tags/")`). The API
+flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
+`api_base_url`, else a connected GitHub plugin on the same service, else
+the service endpoint, else the payload's `repository.url`.
+
+Unlike identity/deployment/lifecycle (which act as the OAuth user),
+commit-sync runs without an actor and authenticates with a **service**
+credential in one of two modes, resolved per call:
+
+- **PAT** — a static `access_token`.
+- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
+  and mints a short-lived **installation token** (cached process-wide
+  until shortly before it expires), so no static, expiring token is
+  stored. `installation_id` is optional — when unset it is discovered
+  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
+  The App needs **Contents: Read-only**.
+
+## Integration options
+
+Asked once per Integration and delivered to every capability on
+`PluginContext.integration_options`:
+
+| Option   | Required  | Description                                                             |
+| -------- | --------- | ----------------------------------------------------------------------- |
+| `flavor` | yes       | `github`, `ghec`, or `ghes`.                                            |
+| `host`   | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`). |
+
+## Capability options
+
+Scoped to one capability and delivered on
+`PluginContext.capability_options`:
+
+| Capability  | Option               | Description                                                                             |
+| ----------- | -------------------- | --------------------------------------------------------------------------------------- |
+| `identity`  | `default_scopes`     | Space-separated OAuth scopes (default: `read:user user:email repo workflow`).            |
+| `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`.             |
+
+## Credentials
+
+One credential store per Integration — every capability receives the
+same decrypted blob. All fields are individually optional and validated
+per call, so an identity-only or App-only Integration is valid:
+
+| Field             | Used by            | Description                                       |
+| ----------------- | ------------------ | ------------------------------------------------- |
+| `access_token`    | service (PAT mode) | Static personal/service token.                    |
+| `app_id`          | service (App mode) | GitHub App identifier.                            |
+| `private_key`     | service (App mode) | App private key — raw PEM or base64-encoded PEM.  |
+| `installation_id` | service (App mode) | Optional; discovered from the repo when unset.    |
+| `client_id`       | `identity`         | OAuth App client id.                              |
+| `client_secret`   | `identity`         | OAuth App client secret.                          |
+
+For `commit-sync`, `pr-sync`, and `deployment` provide **either**
+`access_token` **or** `app_id` + `private_key`. `lifecycle` acts as the
+user and takes only `access_token` (or `token`) — it does not fall back
+to GitHub App credentials.
+
+## License
+
+BSD-3-Clause.

{imbi_plugin_github-2.17.0 → imbi_plugin_github-2.19.0}/pyproject.toml

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

imbi_plugin_github-2.19.0/src/imbi/plugins/github/README.md

@@ -0,0 +1,135 @@
+# imbi-plugin-github
+
+GitHub plugin for Imbi. A single plugin — slug **`github`** — backs every
+GitHub Integration; the integration-level `flavor` option selects
+github.com (`github`), GitHub Enterprise Cloud (`ghec`), or GitHub
+Enterprise Server (`ghes`), and `host` names the tenant or appliance.
+
+## Capabilities
+
+| Kind              | Handler                   |
+| ----------------- | ------------------------- |
+| `identity`        | `GitHubIdentity`          |
+| `deployment`      | `GitHubDeployment`        |
+| `lifecycle`       | `GitHubLifecycle`         |
+| `webhook-actions` | `GitHubWebhookActions`    |
+| `commit-sync`     | `GitHubCommitSync`        |
+| `pr-sync`         | `GitHubPullRequestSync`   |
+| `analysis`        | `GitHubDoctor`            |
+
+### Identity
+
+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
+
+Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
+plus tag and release creation. Promote behaviour is inferred from the
+ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
++ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
+`env_payloads` and arrive on `PluginContext.environment_config`.
+
+### Lifecycle
+
+Reacts to project archive / unarchive by archiving the matching repo via
+`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
+`archive_target_org` option is set, archive **also** transfers the repo to
+that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
+moving sunset projects into a dedicated "archive" org so they no longer
+crowd primary-org searches.
+
+GitHub refuses to transfer archived repos, so an already-archived source
+is briefly unarchived, transferred, and re-archived at the destination.
+On unarchive the plugin only flips `archived` back to `false` at the
+repo's current location — it does **not** transfer back to the original
+org.
+
+Archiving requires admin scope on the repo; transferring additionally
+requires admin permission on the target organization.
+
+### Webhook actions (commit / tag / PR sync)
+
+The `webhook-actions` capability exposes the actions the gateway
+dispatches from webhook deliveries. A `WebhookRule.handler` is
+`"<plugin_slug>#<action_name>"`, and the slug is the **plugin** slug —
+`github` — not the capability kind:
+
+| Action                | Handler                      | Records into ClickHouse |
+| --------------------- | ---------------------------- | ----------------------- |
+| `sync_commits`        | `github#sync_commits`        | `commits`               |
+| `sync_tags`           | `github#sync_tags`           | `tags`                  |
+| `sync_pull_requests`  | `github#sync_pull_requests`  | `pull_requests`         |
+
+`sync_commits` and `sync_tags` are dispatched from `push` deliveries;
+`sync_pull_requests` from `pull_request` deliveries.
+
+`sync_commits` fetches the full set of commits in a push via the compare
+API (paginated, so it isn't capped by the 20-commit inline payload limit);
+`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
+full tag list. Branch/tag gating is the rule's CEL `filter_expression`,
+which evaluates against the recorded event — the webhook body is under
+`payload` (e.g. `payload.ref == "refs/heads/main"`,
+`payload.ref.startsWith("refs/tags/")`). The API
+flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
+`api_base_url`, else a connected GitHub plugin on the same service, else
+the service endpoint, else the payload's `repository.url`.
+
+Unlike identity/deployment/lifecycle (which act as the OAuth user),
+commit-sync runs without an actor and authenticates with a **service**
+credential in one of two modes, resolved per call:
+
+- **PAT** — a static `access_token`.
+- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
+  and mints a short-lived **installation token** (cached process-wide
+  until shortly before it expires), so no static, expiring token is
+  stored. `installation_id` is optional — when unset it is discovered
+  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
+  The App needs **Contents: Read-only**.
+
+## Integration options
+
+Asked once per Integration and delivered to every capability on
+`PluginContext.integration_options`:
+
+| Option   | Required  | Description                                                             |
+| -------- | --------- | ----------------------------------------------------------------------- |
+| `flavor` | yes       | `github`, `ghec`, or `ghes`.                                            |
+| `host`   | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`). |
+
+## Capability options
+
+Scoped to one capability and delivered on
+`PluginContext.capability_options`:
+
+| Capability  | Option               | Description                                                                             |
+| ----------- | -------------------- | --------------------------------------------------------------------------------------- |
+| `identity`  | `default_scopes`     | Space-separated OAuth scopes (default: `read:user user:email repo workflow`).            |
+| `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`.             |
+
+## Credentials
+
+One credential store per Integration — every capability receives the
+same decrypted blob. All fields are individually optional and validated
+per call, so an identity-only or App-only Integration is valid:
+
+| Field             | Used by            | Description                                       |
+| ----------------- | ------------------ | ------------------------------------------------- |
+| `access_token`    | service (PAT mode) | Static personal/service token.                    |
+| `app_id`          | service (App mode) | GitHub App identifier.                            |
+| `private_key`     | service (App mode) | App private key — raw PEM or base64-encoded PEM.  |
+| `installation_id` | service (App mode) | Optional; discovered from the repo when unset.    |
+| `client_id`       | `identity`         | OAuth App client id.                              |
+| `client_secret`   | `identity`         | OAuth App client secret.                          |
+
+For `commit-sync`, `pr-sync`, and `deployment` provide **either**
+`access_token` **or** `app_id` + `private_key`. `lifecycle` acts as the
+user and takes only `access_token` (or `token`) — it does not fall back
+to GitHub App credentials.
+
+## License
+
+BSD-3-Clause.

{imbi_plugin_github-2.17.0 → imbi_plugin_github-2.19.0}/src/imbi/plugins/github/deployment.py

@@ -26,6 +26,7 @@ import contextlib
 import datetime
 import hashlib
 import logging
+import re
 import time
 import typing
 import urllib.parse
@@ -1002,10 +1003,16 @@ class GitHubDeployment(DeploymentCapability):
         with explicit pagination if it ever needs to.
         """
         page_size = max(1, min(limit, 100))
+        # One run commonly backs several deployments in a sweep; cache
+        # the triggering-actor lookup by run id so we resolve each run
+        # at most once. Shared across the parallel per-env fan-out.
+        run_cache: dict[str, tuple[str, str] | None] = {}
         async with self._client(ctx, credentials) as client:
             per_env = await asyncio.gather(
                 *(
-                    self._list_deployments_for_env(client, env, page_size)
+                    self._list_deployments_for_env(
+                        client, env, page_size, run_cache
+                    )
                     for env in environments
                 )
             )
@@ -1035,6 +1042,7 @@ class GitHubDeployment(DeploymentCapability):
         client: httpx.AsyncClient,
         environment: str,
         page_size: int,
+        run_cache: dict[str, tuple[str, str] | None],
     ) -> list[RemoteDeployment]:
         try:
             resp = await client.get(
@@ -1067,7 +1075,7 @@ class GitHubDeployment(DeploymentCapability):
         observed: list[RemoteDeployment] = []
         for deployment in deployments:
             run = await self._observe_deployment(
-                client, environment, deployment
+                client, environment, deployment, run_cache
             )
             if run is not None:
                 observed.append(run)
@@ -1078,6 +1086,7 @@ class GitHubDeployment(DeploymentCapability):
         client: httpx.AsyncClient,
         environment: str,
         deployment: dict[str, typing.Any],
+        run_cache: dict[str, tuple[str, str] | None],
     ) -> RemoteDeployment | None:
         deployment_id = deployment.get('id')
         sha = deployment.get('sha')
@@ -1113,6 +1122,18 @@ class GitHubDeployment(DeploymentCapability):
             creator_id = creator_dict.get('id')
             if isinstance(creator_id, int):
                 creator_subject = str(creator_id)
+            # Deployments made by an Actions workflow carry the app bot
+            # as creator (``deployer[bot]``), never the human who
+            # triggered the run. Re-attribute to the run's triggering
+            # actor so the host can resolve the deploy to a real user.
+            if _is_bot(creator_dict):
+                run_id = _run_id_from_status_url(status_url)
+                if run_id is not None:
+                    actor = await self._resolve_triggering_actor(
+                        client, run_id, run_cache
+                    )
+                    if actor is not None:
+                        creator_login, creator_subject = actor
         return RemoteDeployment(
             environment=environment,
             sha=str(sha),
@@ -1128,6 +1149,53 @@ class GitHubDeployment(DeploymentCapability):
             creator_subject=creator_subject,
         )
 
+    async def _resolve_triggering_actor(
+        self,
+        client: httpx.AsyncClient,
+        run_id: str,
+        run_cache: dict[str, tuple[str, str] | None],
+    ) -> tuple[str, str] | None:
+        """Resolve a workflow run's human trigger to ``(login, subject)``.
+
+        Attributes a bot-created deployment to the person who started
+        the Actions run via ``GET /actions/runs/{run_id}``, preferring
+        ``triggering_actor`` (the account that re-ran or dispatched the
+        run) and falling back to ``actor``. Best-effort: a fetch/parse
+        error, a missing actor, or an actor that is itself a bot yields
+        ``None`` so the caller keeps the bot creator -- attribution must
+        never fail the resync. Results (including ``None``) are cached
+        per sweep because one run backs several deployments.
+        """
+        if run_id in run_cache:
+            return run_cache[run_id]
+        result: tuple[str, str] | None = None
+        try:
+            resp = await client.get(f'/actions/runs/{run_id}')
+            resp.raise_for_status()
+            run = typing.cast(dict[str, typing.Any], resp.json())
+        except (httpx.HTTPError, PluginAuthenticationFailed, ValueError):
+            LOGGER.warning(
+                'Failed to fetch workflow run %s for deploy attribution',
+                run_id,
+                exc_info=True,
+            )
+            run_cache[run_id] = None
+            return None
+        actor_raw = run.get('triggering_actor') or run.get('actor')
+        if isinstance(actor_raw, dict):
+            actor = typing.cast(dict[str, typing.Any], actor_raw)
+            login = actor.get('login')
+            actor_id = actor.get('id')
+            if (
+                isinstance(login, str)
+                and login
+                and isinstance(actor_id, int)
+                and not _is_bot(actor)
+            ):
+                result = (login, str(actor_id))
+        run_cache[run_id] = result
+        return result
+
     async def _release_notes_for_ref(
         self, client: httpx.AsyncClient, ref: str
     ) -> str | None:
@@ -1195,6 +1263,38 @@ class GitHubDeployment(DeploymentCapability):
         return _to_event_status(state), str(log_url) if log_url else None
 
 
+_RUN_ID_RE = re.compile(r'/actions/runs/(\d+)')
+
+
+def _is_bot(user: dict[str, typing.Any]) -> bool:
+    """Return ``True`` when a GitHub user object denotes an app/bot.
+
+    GitHub marks app identities with ``type == 'Bot'`` on the user
+    object and gives them a ``login`` suffixed ``[bot]``
+    (``github-actions[bot]``, ``deployer[bot]``). Either signal alone is
+    sufficient; both comparisons are case-insensitive.
+    """
+    if str(user.get('type') or '').lower() == 'bot':
+        return True
+    login = user.get('login')
+    return isinstance(login, str) and login.lower().endswith('[bot]')
+
+
+def _run_id_from_status_url(url: str | None) -> str | None:
+    """Extract the Actions run id from a deployment status URL.
+
+    A GitHub Actions deploy posts its status ``log_url``/``target_url``
+    pointing at the workflow run
+    (``.../actions/runs/{run_id}`` optionally followed by
+    ``/job/{job_id}``). Any URL that is not an Actions run link yields
+    ``None``.
+    """
+    if not url:
+        return None
+    match = _RUN_ID_RE.search(url)
+    return match.group(1) if match else None
+
+
 def _to_event_status(github_state: str) -> DeploymentEventStatus:
     """Map a GitHub deployment-status ``state`` to the host vocabulary.
 

{imbi_plugin_github-2.17.0 → imbi_plugin_github-2.19.0}/tests/test_deployment.py

@@ -1297,6 +1297,232 @@ class ListRecentDeploymentsTestCase(unittest.IsolatedAsyncioTestCase):
         self.assertTrue(all(e.release_notes is None for e in events))
         self.assertEqual(first.call_count, 1)
 
+    @respx.mock
+    async def test_bot_creator_attributed_to_triggering_actor(self) -> None:
+        # A workflow-created deployment lists the app bot as creator; the
+        # status URL points at the Actions run, so attribution follows to
+        # the run's triggering actor (the human who started it).
+        respx.get('https://api.github.com/repos/octo/demo/deployments').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'id': 123,
+                        'sha': 'botsha',
+                        'ref': 'main',
+                        'created_at': '2026-05-13T14:00:00Z',
+                        'creator': {
+                            'login': 'deployer[bot]',
+                            'id': 111,
+                            'type': 'Bot',
+                        },
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/123/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'state': 'success',
+                        'log_url': (
+                            'https://github.com/octo/demo'
+                            '/actions/runs/9001/job/55'
+                        ),
+                        'created_at': '2026-05-13T14:01:00Z',
+                    }
+                ],
+            )
+        )
+        run = respx.get(
+            'https://api.github.com/repos/octo/demo/actions/runs/9001'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'triggering_actor': {'login': 'octocat', 'id': 583231},
+                    'actor': {'login': 'someone-else', 'id': 42},
+                },
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/main'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        plugin = GitHubDeployment()
+        events = await plugin.list_recent_deployments(
+            _ctx(), _CREDS, ['production']
+        )
+        self.assertEqual(len(events), 1)
+        self.assertTrue(run.called)
+        self.assertEqual(events[0].creator, 'octocat')
+        self.assertEqual(events[0].creator_subject, '583231')
+
+    @respx.mock
+    async def test_bot_detection_is_case_insensitive(self) -> None:
+        # Bot detection must not depend on GitHub's casing: a creator
+        # with type 'bot' and a mixed-case '[Bot]' login suffix is still
+        # re-attributed to the run's triggering actor.
+        respx.get('https://api.github.com/repos/octo/demo/deployments').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'id': 123,
+                        'sha': 'botsha',
+                        'ref': 'main',
+                        'created_at': '2026-05-13T14:00:00Z',
+                        'creator': {
+                            'login': 'Deployer[Bot]',
+                            'id': 111,
+                            'type': 'bot',
+                        },
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/123/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'state': 'success',
+                        'log_url': (
+                            'https://github.com/octo/demo'
+                            '/actions/runs/9001/job/55'
+                        ),
+                        'created_at': '2026-05-13T14:01:00Z',
+                    }
+                ],
+            )
+        )
+        run = respx.get(
+            'https://api.github.com/repos/octo/demo/actions/runs/9001'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    'triggering_actor': {'login': 'octocat', 'id': 583231},
+                },
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/main'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        plugin = GitHubDeployment()
+        events = await plugin.list_recent_deployments(
+            _ctx(), _CREDS, ['production']
+        )
+        self.assertEqual(len(events), 1)
+        self.assertTrue(run.called)
+        self.assertEqual(events[0].creator, 'octocat')
+        self.assertEqual(events[0].creator_subject, '583231')
+
+    @respx.mock
+    async def test_bot_creator_kept_when_run_fetch_fails(self) -> None:
+        # The run lookup 500s; attribution degrades gracefully to the bot
+        # creator rather than raising and failing the resync.
+        respx.get('https://api.github.com/repos/octo/demo/deployments').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'id': 123,
+                        'sha': 'botsha',
+                        'ref': 'main',
+                        'created_at': '2026-05-13T14:00:00Z',
+                        'creator': {
+                            'login': 'github-actions[bot]',
+                            'id': 111,
+                        },
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/123/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'state': 'success',
+                        'target_url': (
+                            'https://github.com/octo/demo/actions/runs/9001'
+                        ),
+                        'created_at': '2026-05-13T14:01:00Z',
+                    }
+                ],
+            )
+        )
+        run = respx.get(
+            'https://api.github.com/repos/octo/demo/actions/runs/9001'
+        ).mock(return_value=httpx.Response(500, json={'message': 'oops'}))
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/main'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        plugin = GitHubDeployment()
+        events = await plugin.list_recent_deployments(
+            _ctx(), _CREDS, ['production']
+        )
+        self.assertEqual(len(events), 1)
+        self.assertTrue(run.called)
+        self.assertEqual(events[0].creator, 'github-actions[bot]')
+        self.assertEqual(events[0].creator_subject, '111')
+
+    @respx.mock
+    async def test_human_creator_skips_run_lookup(self) -> None:
+        # A human-created deployment must never issue the extra run
+        # fetch; the creator is used as-is.
+        respx.get('https://api.github.com/repos/octo/demo/deployments').mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'id': 123,
+                        'sha': 'humansha',
+                        'ref': 'main',
+                        'created_at': '2026-05-13T14:00:00Z',
+                        'creator': {'login': 'octocat', 'id': 583231},
+                    }
+                ],
+            )
+        )
+        respx.get(
+            'https://api.github.com/repos/octo/demo/deployments/123/statuses'
+        ).mock(
+            return_value=httpx.Response(
+                200,
+                json=[
+                    {
+                        'state': 'success',
+                        'log_url': (
+                            'https://github.com/octo/demo/actions/runs/9001'
+                        ),
+                        'created_at': '2026-05-13T14:01:00Z',
+                    }
+                ],
+            )
+        )
+        run = respx.get(
+            'https://api.github.com/repos/octo/demo/actions/runs/9001'
+        ).mock(return_value=httpx.Response(200, json={}))
+        respx.get(
+            'https://api.github.com/repos/octo/demo/releases/tags/main'
+        ).mock(return_value=httpx.Response(404, json={'message': 'Not Found'}))
+        plugin = GitHubDeployment()
+        events = await plugin.list_recent_deployments(
+            _ctx(), _CREDS, ['production']
+        )
+        self.assertEqual(len(events), 1)
+        self.assertFalse(run.called)
+        self.assertEqual(events[0].creator, 'octocat')
+        self.assertEqual(events[0].creator_subject, '583231')
+
 
 class GetReleaseNotesTestCase(unittest.IsolatedAsyncioTestCase):
     @respx.mock

imbi_plugin_github-2.17.0/PKG-INFO

@@ -1,126 +0,0 @@
-Metadata-Version: 2.4
-Name: imbi-plugin-github
-Version: 2.17.0
-Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
-Author-email: "Gavin M. Roy" <gavinr@aweber.com>
-License-Expression: BSD-3-Clause
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-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.17.0
-Requires-Dist: pydantic>=2
-Requires-Dist: pyjwt[crypto]>=2.8
-Description-Content-Type: text/markdown
-
-# imbi-plugin-github
-
-GitHub plugins for Imbi. Three flavors (github.com, GitHub Enterprise Cloud,
-GitHub Enterprise Server) of each plugin type so the admin UI can wire
-projects to the right backend.
-
-## Plugin types
-
-| Type       | Slugs                                                                |
-| ---------- | -------------------------------------------------------------------- |
-| Identity   | `github`, `github-enterprise-cloud`, `github-enterprise-server`      |
-| Deployment | `github-deployment`, `github-deployment-ec`, `github-deployment-es`  |
-| Lifecycle  | `github-lifecycle`, `github-lifecycle-ec`, `github-lifecycle-es`     |
-| Webhook    | `github-commit-sync`                                                  |
-
-### Identity
-
-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
-
-Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
-plus tag and release creation. Promote behaviour is inferred from the
-ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
-+ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
-`env_payloads` and arrive on `PluginContext.environment_config`.
-
-### Lifecycle
-
-Reacts to project archive / unarchive by archiving the matching repo via
-`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
-`archive_target_org` option is set, archive **also** transfers the repo to
-that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
-moving sunset projects into a dedicated "archive" org so they no longer
-crowd primary-org searches.
-
-GitHub refuses to transfer archived repos, so an already-archived source
-is briefly unarchived, transferred, and re-archived at the destination.
-On unarchive the plugin only flips `archived` back to `false` at the
-repo's current location — it does **not** transfer back to the original
-org.
-
-Archiving requires admin scope on the repo; transferring additionally
-requires admin permission on the target organization.
-
-### Webhook (commit / tag sync)
-
-A single `github-commit-sync` webhook-action plugin exposes two actions
-the gateway dispatches on `push` deliveries:
-
-| Action         | Handler                          | Records into ClickHouse |
-| -------------- | -------------------------------- | ----------------------- |
-| `sync_commits` | `github-commit-sync#sync_commits`| `commits`               |
-| `sync_tags`    | `github-commit-sync#sync_tags`   | `tags`                  |
-
-`sync_commits` fetches the full set of commits in a push via the compare
-API (paginated, so it isn't capped by the 20-commit inline payload limit);
-`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
-full tag list. Branch/tag gating is the rule's CEL `filter_expression`
-(e.g. `ref == "refs/heads/main"`, `ref.startsWith("refs/tags/")`). The API
-flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
-`api_base_url`, else a connected GitHub plugin on the same service, else
-the service endpoint, else the payload's `repository.url`.
-
-Unlike identity/deployment/lifecycle (which act as the OAuth user),
-commit-sync runs without an actor and authenticates with a **service**
-credential in one of two modes, resolved per call:
-
-- **PAT** — a static `access_token`.
-- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
-  and mints a short-lived **installation token** (cached process-wide
-  until shortly before it expires), so no static, expiring token is
-  stored. `installation_id` is optional — when unset it is discovered
-  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
-  The App needs **Contents: Read-only**.
-
-## Manifest options (identity)
-
-| 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 repo workflow`). |
-
-## Credentials (identity)
-
-| Field            | Required |
-| ---------------- | -------- |
-| `client_id`      | yes      |
-| `client_secret`  | yes      |
-
-## Credentials (commit-sync)
-
-Provide **either** the PAT field **or** the GitHub App fields (all
-individually optional; validated per call):
-
-| Field             | Mode | Description                                            |
-| ----------------- | ---- | ------------------------------------------------------ |
-| `access_token`    | PAT  | Static personal/service token.                         |
-| `app_id`          | App  | GitHub App identifier.                                 |
-| `private_key`     | App  | App private key — raw PEM or base64-encoded PEM.       |
-| `installation_id` | App  | Optional; discovered from the repo when unset.         |
-
-## License
-
-BSD-3-Clause.

imbi_plugin_github-2.17.0/README.md

@@ -1,107 +0,0 @@
-# imbi-plugin-github
-
-GitHub plugins for Imbi. Three flavors (github.com, GitHub Enterprise Cloud,
-GitHub Enterprise Server) of each plugin type so the admin UI can wire
-projects to the right backend.
-
-## Plugin types
-
-| Type       | Slugs                                                                |
-| ---------- | -------------------------------------------------------------------- |
-| Identity   | `github`, `github-enterprise-cloud`, `github-enterprise-server`      |
-| Deployment | `github-deployment`, `github-deployment-ec`, `github-deployment-es`  |
-| Lifecycle  | `github-lifecycle`, `github-lifecycle-ec`, `github-lifecycle-es`     |
-| Webhook    | `github-commit-sync`                                                  |
-
-### Identity
-
-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
-
-Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
-plus tag and release creation. Promote behaviour is inferred from the
-ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
-+ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
-`env_payloads` and arrive on `PluginContext.environment_config`.
-
-### Lifecycle
-
-Reacts to project archive / unarchive by archiving the matching repo via
-`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
-`archive_target_org` option is set, archive **also** transfers the repo to
-that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
-moving sunset projects into a dedicated "archive" org so they no longer
-crowd primary-org searches.
-
-GitHub refuses to transfer archived repos, so an already-archived source
-is briefly unarchived, transferred, and re-archived at the destination.
-On unarchive the plugin only flips `archived` back to `false` at the
-repo's current location — it does **not** transfer back to the original
-org.
-
-Archiving requires admin scope on the repo; transferring additionally
-requires admin permission on the target organization.
-
-### Webhook (commit / tag sync)
-
-A single `github-commit-sync` webhook-action plugin exposes two actions
-the gateway dispatches on `push` deliveries:
-
-| Action         | Handler                          | Records into ClickHouse |
-| -------------- | -------------------------------- | ----------------------- |
-| `sync_commits` | `github-commit-sync#sync_commits`| `commits`               |
-| `sync_tags`    | `github-commit-sync#sync_tags`   | `tags`                  |
-
-`sync_commits` fetches the full set of commits in a push via the compare
-API (paginated, so it isn't capped by the 20-commit inline payload limit);
-`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
-full tag list. Branch/tag gating is the rule's CEL `filter_expression`
-(e.g. `ref == "refs/heads/main"`, `ref.startsWith("refs/tags/")`). The API
-flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
-`api_base_url`, else a connected GitHub plugin on the same service, else
-the service endpoint, else the payload's `repository.url`.
-
-Unlike identity/deployment/lifecycle (which act as the OAuth user),
-commit-sync runs without an actor and authenticates with a **service**
-credential in one of two modes, resolved per call:
-
-- **PAT** — a static `access_token`.
-- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
-  and mints a short-lived **installation token** (cached process-wide
-  until shortly before it expires), so no static, expiring token is
-  stored. `installation_id` is optional — when unset it is discovered
-  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
-  The App needs **Contents: Read-only**.
-
-## Manifest options (identity)
-
-| 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 repo workflow`). |
-
-## Credentials (identity)
-
-| Field            | Required |
-| ---------------- | -------- |
-| `client_id`      | yes      |
-| `client_secret`  | yes      |
-
-## Credentials (commit-sync)
-
-Provide **either** the PAT field **or** the GitHub App fields (all
-individually optional; validated per call):
-
-| Field             | Mode | Description                                            |
-| ----------------- | ---- | ------------------------------------------------------ |
-| `access_token`    | PAT  | Static personal/service token.                         |
-| `app_id`          | App  | GitHub App identifier.                                 |
-| `private_key`     | App  | App private key — raw PEM or base64-encoded PEM.       |
-| `installation_id` | App  | Optional; discovered from the repo when unset.         |
-
-## License
-
-BSD-3-Clause.

imbi_plugin_github-2.17.0/src/imbi/plugins/github/README.md

@@ -1,107 +0,0 @@
-# imbi-plugin-github
-
-GitHub plugins for Imbi. Three flavors (github.com, GitHub Enterprise Cloud,
-GitHub Enterprise Server) of each plugin type so the admin UI can wire
-projects to the right backend.
-
-## Plugin types
-
-| Type       | Slugs                                                                |
-| ---------- | -------------------------------------------------------------------- |
-| Identity   | `github`, `github-enterprise-cloud`, `github-enterprise-server`      |
-| Deployment | `github-deployment`, `github-deployment-ec`, `github-deployment-es`  |
-| Lifecycle  | `github-lifecycle`, `github-lifecycle-ec`, `github-lifecycle-es`     |
-| Webhook    | `github-commit-sync`                                                  |
-
-### Identity
-
-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
-
-Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
-plus tag and release creation. Promote behaviour is inferred from the
-ref shape by the host (semver → trigger Deployment, raw SHA → cut tag
-+ Release).  Per-env workflow inputs ride on the `USES_PLUGIN` edge as
-`env_payloads` and arrive on `PluginContext.environment_config`.
-
-### Lifecycle
-
-Reacts to project archive / unarchive by archiving the matching repo via
-`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
-`archive_target_org` option is set, archive **also** transfers the repo to
-that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
-moving sunset projects into a dedicated "archive" org so they no longer
-crowd primary-org searches.
-
-GitHub refuses to transfer archived repos, so an already-archived source
-is briefly unarchived, transferred, and re-archived at the destination.
-On unarchive the plugin only flips `archived` back to `false` at the
-repo's current location — it does **not** transfer back to the original
-org.
-
-Archiving requires admin scope on the repo; transferring additionally
-requires admin permission on the target organization.
-
-### Webhook (commit / tag sync)
-
-A single `github-commit-sync` webhook-action plugin exposes two actions
-the gateway dispatches on `push` deliveries:
-
-| Action         | Handler                          | Records into ClickHouse |
-| -------------- | -------------------------------- | ----------------------- |
-| `sync_commits` | `github-commit-sync#sync_commits`| `commits`               |
-| `sync_tags`    | `github-commit-sync#sync_tags`   | `tags`                  |
-
-`sync_commits` fetches the full set of commits in a push via the compare
-API (paginated, so it isn't capped by the 20-commit inline payload limit);
-`sync_tags` records the pushed tag and, with `reconcile_all`, the repo's
-full tag list. Branch/tag gating is the rule's CEL `filter_expression`
-(e.g. `ref == "refs/heads/main"`, `ref.startsWith("refs/tags/")`). The API
-flavor (github.com / GHEC / GHES) is resolved at runtime — explicit
-`api_base_url`, else a connected GitHub plugin on the same service, else
-the service endpoint, else the payload's `repository.url`.
-
-Unlike identity/deployment/lifecycle (which act as the OAuth user),
-commit-sync runs without an actor and authenticates with a **service**
-credential in one of two modes, resolved per call:
-
-- **PAT** — a static `access_token`.
-- **GitHub App** — `app_id` + `private_key`; the plugin signs an App JWT
-  and mints a short-lived **installation token** (cached process-wide
-  until shortly before it expires), so no static, expiring token is
-  stored. `installation_id` is optional — when unset it is discovered
-  from the pushed repository (`GET /repos/{owner}/{repo}/installation`).
-  The App needs **Contents: Read-only**.
-
-## Manifest options (identity)
-
-| 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 repo workflow`). |
-
-## Credentials (identity)
-
-| Field            | Required |
-| ---------------- | -------- |
-| `client_id`      | yes      |
-| `client_secret`  | yes      |
-
-## Credentials (commit-sync)
-
-Provide **either** the PAT field **or** the GitHub App fields (all
-individually optional; validated per call):
-
-| Field             | Mode | Description                                            |
-| ----------------- | ---- | ------------------------------------------------------ |
-| `access_token`    | PAT  | Static personal/service token.                         |
-| `app_id`          | App  | GitHub App identifier.                                 |
-| `private_key`     | App  | App private key — raw PEM or base64-encoded PEM.       |
-| `installation_id` | App  | Optional; discovered from the repo when unset.         |
-
-## License
-
-BSD-3-Clause.