hyperfluid 0.1.0__py3-none-any.whl

hyperfluid/api/git_hub_runners.py

@@ -0,0 +1,1216 @@
+# this file is @generated
+"""Git hub runners API."""
+
+from __future__ import annotations
+
+import builtins
+import typing as t
+from uuid import UUID
+
+from .. import models as _models
+from ..models import (
+    CreateGithubConnectionRequest,
+    CreateGithubRunnerRequest,
+    GithubConnectionCredentialDto,
+    GithubConnectionResponse,
+    GithubConnectionTarget,
+    GithubRunnerEgressModeDto,
+    GithubRunnerEgressModeDtoLiteral,
+    GithubRunnerResponse,
+    GithubRunnerScope,
+    RunnerFlavorDto,
+    UpdateGithubConnectionRequest,
+    UpdateGithubRunnerRequest,
+)
+from ..serialization import UNSET, Unset, to_json_value
+from ._response import async_to_raw_response_wrapper, to_raw_response_wrapper
+from .common import (
+    ApiBaseAsync,
+    ApiBaseSync,
+    ApiRequest,
+    Timeout,
+    decode_response,
+    encode_path_param,
+)
+
+
+class AsyncGitHubRunners(ApiBaseAsync):
+    """Git hub runners API, for asyncio."""
+
+    @property
+    def with_raw_response(self) -> AsyncGitHubRunnersWithRawResponse:
+        """These methods, returning an :class:`APIResponse` with the status and headers."""
+        return AsyncGitHubRunnersWithRawResponse(self)
+
+    async def list_organization_github_connections(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubConnectionResponse]:
+        """List the org's `GithubConnection`s (metadata only, never credentials)."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/github-connections",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubConnectionResponse])
+
+    async def create_organization_github_connection(
+        self,
+        organization_id: UUID,
+        *,
+        credential: GithubConnectionCredentialDto,
+        name: str,
+        base_url: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubConnectionResponse:
+        """Create a `GithubConnection`: an org-scoped user-secret holding the GitHub
+        credential (PAT or App key). Write-only — no read endpoint ever returns it.
+
+        ## The credential is proved against GitHub before it is stored
+        A credential is only worth storing if GitHub accepts it, and the cost of
+        finding out later is high: an unusable credential is accepted silently
+        today, and the first symptom is a pool that never comes online, with the
+        real reason buried in an ARC listener log the user cannot see. So the
+        connection is used, once, before anything is written — and if GitHub
+        refuses it, the 400 carries GitHub's own sentence ("Bad credentials",
+        "Integration not found", …).
+
+        The same round trip is what makes `installation_id` optional for the App
+        case: `GET /app/installations` answers it. See [`resolve_app_installation`].
+
+        :param base_url: GitHub base URL. Defaults to `https://github.com`; set for GHES.
+        :param name: Connection name — a DNS-1123-style label (lowercase alphanumerics and hyphens), unique per organization."""
+        response = await self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/github-connections",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateGithubConnectionRequest(
+                        base_url=base_url,
+                        credential=credential,
+                        name=name,
+                    ),
+                    CreateGithubConnectionRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubConnectionResponse)
+
+    async def update_organization_github_connection(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        credential: GithubConnectionCredentialDto,
+        base_url: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubConnectionResponse:
+        """Update a `GithubConnection` in place: rotate the stored credential, and
+        optionally move the connection to a different GitHub host.
+
+        ## Why the credential is always required
+        The stored credential is write-only — no endpoint hands one back — so there
+        is nothing here to partially edit. Requiring it also means every update
+        re-proves a working credential against the *effective* host before anything
+        is overwritten, which is what makes the failure mode "GitHub refused this,
+        nothing changed" instead of "your pools stop renewing their registration
+        token an hour from now".
+
+        The name is not editable: it is what every pool's `connection_secret_name`
+        resolves through, and renaming it would orphan them. Rename = create the new
+        one, move the pools, delete the old one.
+
+        ## Propagation
+        The operator re-projects each pool's `githubConfigSecret` from this secret
+        on every reconcile, so a rotation reaches running pools on their next tick
+        (~2 minutes for a healthy pool) with no pool edit and no restart.
+
+        :param base_url: GitHub base URL. Absent keeps the stored host; changing it is refused while any runner pool still registers against the old one."""
+        response = await self._request(
+            ApiRequest(
+                method="put",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                json_body=to_json_value(
+                    UpdateGithubConnectionRequest(
+                        base_url=base_url,
+                        credential=credential,
+                    ),
+                    UpdateGithubConnectionRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubConnectionResponse)
+
+    async def delete_organization_github_connection(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """Delete a `GithubConnection` by name.
+
+        Refuses while any pool still references it (409): a pool whose connection
+        disappeared keeps its already-projected `githubConfigSecret` and then starts
+        failing token refreshes with no local signal — delete the pools first."""
+        await self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    async def list_organization_github_connection_targets(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubConnectionTarget]:
+        """List every org/user a stored connection can register a runner pool on.
+
+        This is what makes the pool-create form fill itself in: the response carries
+        the organization login (the value `scope` needs) and, for a GitHub App, the
+        installation id — the number users were previously copying out of the tail
+        of a GitHub settings URL.
+
+        For an App connection the result is filtered to the installation the
+        connection is pinned to. Offering the App's other installations would be
+        offering pools that cannot work: ARC authenticates with one installation id,
+        and a pool registered on a different org than that installation covers fails
+        at listener startup. An empty result for an App connection therefore means
+        the installation was removed on GitHub's side — which is itself the signal
+        the user needs.
+
+        Requires `secret:read` on the backing secret in addition to
+        `forgejo_runner:read`: nothing is returned *from* the credential, but the
+        credential is used to act as the organization on GitHub, and an org that
+        denies `secret:read` to a role must not have that role drive it."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}/targets",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubConnectionTarget])
+
+    async def list(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubRunnerResponse]:
+        """List all `GithubRunner` pool CRs for the harbor."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubRunnerResponse])
+
+    async def create(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        *,
+        connection: str,
+        name: str,
+        scope: GithubRunnerScope,
+        egress_mode: GithubRunnerEgressModeDto
+        | GithubRunnerEgressModeDtoLiteral
+        | None
+        | Unset = UNSET,
+        extra_egress_fqdns: builtins.list[str] | None | Unset = UNSET,
+        flavor: RunnerFlavorDto | None | Unset = UNSET,
+        max_runners: int | None | Unset = UNSET,
+        min_runners: int | None | Unset = UNSET,
+        runner_group: str | None | Unset = UNSET,
+        runner_image: str | None | Unset = UNSET,
+        runs_on: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Create a `GithubRunner` pool CR for this harbor.
+
+        Validates that the referenced `GithubConnection` exists before creating the
+        CR (fail fast in the UI rather than at reconcile time). Returns 201; 409 if
+        a pool with that name already exists.
+
+        :param connection: Name of the `GithubConnection` holding the credential (as returned by the connections API — the leaf name, not the full secret path).
+        :param extra_egress_fqdns: Extra destinations the pool's network policy allows egress to, beyond the built-in GitHub Actions preset. `host` opens 443/TCP; `host:port` opens that port instead (`deb.debian.org:80`, `registry.corp.example:5000`).
+        :param max_runners: Ceiling on concurrent runners. Defaults to 3.
+        :param min_runners: Warm runners kept idle. Defaults to 0 (scale-to-zero).
+        :param name: Pool name — must be a valid DNS-1123 label, at most 45 characters (GitHub's runner scale-set name limit). The value workflows put in `runs-on:` is the registered scale-set name the operator derives from it and reports back as `status.runner_scale_set_name`.
+        :param runner_group: GitHub runner group (org scope only). Defaults to GitHub's default group.
+        :param runner_image: Runner container image override. Defaults to the platform-pinned `ghcr.io/actions/actions-runner` release.
+        :param runs_on: The name this pool registers under with GitHub — **the value workflows put in `runs-on:`**, and the only thing GitHub schedules a job on for a runner scale set.  Absent (or empty) keeps the name Hyperfluid derives, `<name>-<digest>`, which is unique across the GitHub org by construction. Setting it trades that for a name you choose (`ubuntu-latest`, `hyperfluid-linux-l`, …); the request is rejected with a 409 if another pool on the same GitHub target and runner group already claims it."""
+        response = await self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateGithubRunnerRequest(
+                        connection=connection,
+                        egress_mode=t.cast(
+                            "GithubRunnerEgressModeDto | None | Unset", egress_mode
+                        ),
+                        extra_egress_fqdns=extra_egress_fqdns,
+                        flavor=flavor,
+                        max_runners=max_runners,
+                        min_runners=min_runners,
+                        name=name,
+                        runner_group=runner_group,
+                        runner_image=runner_image,
+                        runs_on=runs_on,
+                        scope=scope,
+                    ),
+                    CreateGithubRunnerRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+    async def retrieve(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Get a single `GithubRunner` pool CR by name (status polling)."""
+        response = await self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+    async def delete(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """Delete a `GithubRunner` pool CR by name.
+
+        Idempotent: 204 even when already absent. The operator's finalizer tears
+        down the `AutoscalingRunnerSet` (ARC deregisters the scale set from
+        GitHub), the config secret, and the network policy via ownerReference GC.
+
+        The 204 is held until the CR is observed gone (bounded — see
+        [`DELETE_SETTLE_BUDGET`]). `Api::delete` only *marks* a finalized object,
+        so returning on its acknowledgement made the client's post-delete refetch
+        race the finalizer and re-render the pool it had just deleted."""
+        await self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    async def update(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        connection: str | None | Unset = UNSET,
+        egress_mode: GithubRunnerEgressModeDto
+        | GithubRunnerEgressModeDtoLiteral
+        | None
+        | Unset = UNSET,
+        extra_egress_fqdns: builtins.list[str] | None | Unset = UNSET,
+        flavor: RunnerFlavorDto | None | Unset = UNSET,
+        max_runners: int | None | Unset = UNSET,
+        min_runners: int | None | Unset = UNSET,
+        runner_group: str | None | Unset = UNSET,
+        runner_image: str | None | Unset = UNSET,
+        runs_on: str | None | Unset = UNSET,
+        scope: GithubRunnerScope | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Edit a `GithubRunner` pool in place.
+
+        Exists because the alternative — delete and recreate — deregisters the scale
+        set from GitHub, which drops the `runs-on:` target and interrupts whatever
+        was running. Every field below can change without that happening.
+
+        ## What the operator does with each field
+        - **`min_runners` / `max_runners`** — a live resize. ARC moves the target
+          count on the existing `AutoscalingRunnerSet`; no pod is recreated and no
+          running job is touched.
+        - **`flavor` / `runner_image`** — a template change. The runner pod spec is
+          rewritten, so jobs already executing finish on the old template and the
+          next ones start on the new one. Nothing is killed mid-job.
+        - **`runner_group`** — re-registers the scale set into another GitHub runner
+          group. Brief, and the scale-set name is unchanged, so `runs-on:` keeps
+          working.
+        - **`runs_on`** — deregisters the scale set and registers it again under a
+          new name. The one edit here that workflows can see, and the one with
+          downtime: GitHub will not move a registration's runner label in place, so
+          the `AutoscalingRunnerSet` is deleted and re-applied (its Kubernetes name
+          is unchanged, as is every other object). ARC drains in-flight runners
+          first, so no job is killed, but the pool accepts nothing until the new
+          registration is live, and a workflow still naming the old value queues
+          until it is updated. `""` hands the name back to the derived one.
+        - **`extra_egress_fqdns`** — the pool's network policy is re-rendered. It
+          replaces the previous list wholesale rather than merging into it. Entries
+          are `host` (443/TCP) or `host:port`.
+        - **`egress_mode`** — the pool's network policy is re-rendered, in place and
+          without recreating a pod. Cilium applies the new policy to the live
+          endpoints, so a job already running keeps its established connections and
+          only its *next* connect is judged by the new posture.
+        - **`connection`** — the pool's config secret is re-projected from the new
+          credential. This is the rotation path: swap in a fresh App key or PAT
+          without the scale set ever leaving GitHub.
+
+        `scope` is deliberately not editable; see [`UpdateGithubRunnerRequest`].
+
+        :param connection: Move the pool to a different `GithubConnection` — the leaf name, same value `CreateGithubRunnerRequest.connection` takes. Used to swap in a rotated credential without deregistering the scale set. The new connection must point at the same GitHub host as the current one.
+        :param extra_egress_fqdns: Replacement egress allow-list (it replaces the previous one wholesale, it is not merged entry by entry). Send `[]` to keep only the built-in GitHub Actions preset. Entries are `host` (443/TCP) or `host:port`.
+        :param max_runners: New concurrency ceiling. Live resize, same as `min_runners`.
+        :param min_runners: New warm-runner floor. Live resize — ARC changes the target without recreating pods.
+        :param runner_group: New GitHub runner group (org scope only). Send `""` to fall back to GitHub's default group.
+        :param runner_image: New runner container image. Rolls the runner template, same as `flavor`. Send `""` to go back to the platform-pinned default.
+        :param runs_on: New `runs-on:` name. Send `""` to go back to the name Hyperfluid derives from the pool name.  Unlike every other field here this one is **not** transparent to running workflows: the scale set is deregistered and registered again under the new name, so a workflow still saying `runs-on: <old name>` queues until it is edited.  It is also the only edit with downtime. GitHub will not move a registration's runner label in place, so the `AutoscalingRunnerSet` is deleted and re-applied (under its unchanged Kubernetes name). ARC drains in-flight runners first — no job is killed — but the pool accepts nothing until the new registration is live. `status.message` names the old value to keep using meanwhile."""
+        response = await self._request(
+            ApiRequest(
+                method="patch",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                json_body=to_json_value(
+                    UpdateGithubRunnerRequest(
+                        connection=connection,
+                        egress_mode=t.cast(
+                            "GithubRunnerEgressModeDto | None | Unset", egress_mode
+                        ),
+                        extra_egress_fqdns=extra_egress_fqdns,
+                        flavor=flavor,
+                        max_runners=max_runners,
+                        min_runners=min_runners,
+                        runner_group=runner_group,
+                        runner_image=runner_image,
+                        runs_on=runs_on,
+                        scope=scope,
+                    ),
+                    UpdateGithubRunnerRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+
+class AsyncGitHubRunnersWithRawResponse:
+    """The methods of :class:`AsyncGitHubRunners`, returning an :class:`APIResponse`."""
+
+    def __init__(self, resource: AsyncGitHubRunners) -> None:
+        self.list_organization_github_connections = async_to_raw_response_wrapper(
+            resource.list_organization_github_connections
+        )
+        self.create_organization_github_connection = async_to_raw_response_wrapper(
+            resource.create_organization_github_connection
+        )
+        self.update_organization_github_connection = async_to_raw_response_wrapper(
+            resource.update_organization_github_connection
+        )
+        self.delete_organization_github_connection = async_to_raw_response_wrapper(
+            resource.delete_organization_github_connection
+        )
+        self.list_organization_github_connection_targets = (
+            async_to_raw_response_wrapper(
+                resource.list_organization_github_connection_targets
+            )
+        )
+        self.list = async_to_raw_response_wrapper(resource.list)
+        self.create = async_to_raw_response_wrapper(resource.create)
+        self.retrieve = async_to_raw_response_wrapper(resource.retrieve)
+        self.delete = async_to_raw_response_wrapper(resource.delete)
+        self.update = async_to_raw_response_wrapper(resource.update)
+
+
+class GitHubRunners(ApiBaseSync):
+    """Git hub runners API."""
+
+    @property
+    def with_raw_response(self) -> GitHubRunnersWithRawResponse:
+        """These methods, returning an :class:`APIResponse` with the status and headers."""
+        return GitHubRunnersWithRawResponse(self)
+
+    def list_organization_github_connections(
+        self,
+        organization_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubConnectionResponse]:
+        """List the org's `GithubConnection`s (metadata only, never credentials)."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/github-connections",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubConnectionResponse])
+
+    def create_organization_github_connection(
+        self,
+        organization_id: UUID,
+        *,
+        credential: GithubConnectionCredentialDto,
+        name: str,
+        base_url: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubConnectionResponse:
+        """Create a `GithubConnection`: an org-scoped user-secret holding the GitHub
+        credential (PAT or App key). Write-only — no read endpoint ever returns it.
+
+        ## The credential is proved against GitHub before it is stored
+        A credential is only worth storing if GitHub accepts it, and the cost of
+        finding out later is high: an unusable credential is accepted silently
+        today, and the first symptom is a pool that never comes online, with the
+        real reason buried in an ARC listener log the user cannot see. So the
+        connection is used, once, before anything is written — and if GitHub
+        refuses it, the 400 carries GitHub's own sentence ("Bad credentials",
+        "Integration not found", …).
+
+        The same round trip is what makes `installation_id` optional for the App
+        case: `GET /app/installations` answers it. See [`resolve_app_installation`].
+
+        :param base_url: GitHub base URL. Defaults to `https://github.com`; set for GHES.
+        :param name: Connection name — a DNS-1123-style label (lowercase alphanumerics and hyphens), unique per organization."""
+        response = self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/github-connections",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateGithubConnectionRequest(
+                        base_url=base_url,
+                        credential=credential,
+                        name=name,
+                    ),
+                    CreateGithubConnectionRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubConnectionResponse)
+
+    def update_organization_github_connection(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        credential: GithubConnectionCredentialDto,
+        base_url: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubConnectionResponse:
+        """Update a `GithubConnection` in place: rotate the stored credential, and
+        optionally move the connection to a different GitHub host.
+
+        ## Why the credential is always required
+        The stored credential is write-only — no endpoint hands one back — so there
+        is nothing here to partially edit. Requiring it also means every update
+        re-proves a working credential against the *effective* host before anything
+        is overwritten, which is what makes the failure mode "GitHub refused this,
+        nothing changed" instead of "your pools stop renewing their registration
+        token an hour from now".
+
+        The name is not editable: it is what every pool's `connection_secret_name`
+        resolves through, and renaming it would orphan them. Rename = create the new
+        one, move the pools, delete the old one.
+
+        ## Propagation
+        The operator re-projects each pool's `githubConfigSecret` from this secret
+        on every reconcile, so a rotation reaches running pools on their next tick
+        (~2 minutes for a healthy pool) with no pool edit and no restart.
+
+        :param base_url: GitHub base URL. Absent keeps the stored host; changing it is refused while any runner pool still registers against the old one."""
+        response = self._request(
+            ApiRequest(
+                method="put",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                json_body=to_json_value(
+                    UpdateGithubConnectionRequest(
+                        base_url=base_url,
+                        credential=credential,
+                    ),
+                    UpdateGithubConnectionRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubConnectionResponse)
+
+    def delete_organization_github_connection(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """Delete a `GithubConnection` by name.
+
+        Refuses while any pool still references it (409): a pool whose connection
+        disappeared keeps its already-projected `githubConfigSecret` and then starts
+        failing token refreshes with no local signal — delete the pools first."""
+        self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    def list_organization_github_connection_targets(
+        self,
+        organization_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubConnectionTarget]:
+        """List every org/user a stored connection can register a runner pool on.
+
+        This is what makes the pool-create form fill itself in: the response carries
+        the organization login (the value `scope` needs) and, for a GitHub App, the
+        installation id — the number users were previously copying out of the tail
+        of a GitHub settings URL.
+
+        For an App connection the result is filtered to the installation the
+        connection is pinned to. Offering the App's other installations would be
+        offering pools that cannot work: ARC authenticates with one installation id,
+        and a pool registered on a different org than that installation covers fails
+        at listener startup. An empty result for an App connection therefore means
+        the installation was removed on GitHub's side — which is itself the signal
+        the user needs.
+
+        Requires `secret:read` on the backing secret in addition to
+        `forgejo_runner:read`: nothing is returned *from* the credential, but the
+        credential is used to act as the organization on GitHub, and an org that
+        denies `secret:read` to a role must not have that role drive it."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/github-connections/{name}/targets",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubConnectionTarget])
+
+    def list(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> builtins.list[GithubRunnerResponse]:
+        """List all `GithubRunner` pool CRs for the harbor."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, list[GithubRunnerResponse])
+
+    def create(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        *,
+        connection: str,
+        name: str,
+        scope: GithubRunnerScope,
+        egress_mode: GithubRunnerEgressModeDto
+        | GithubRunnerEgressModeDtoLiteral
+        | None
+        | Unset = UNSET,
+        extra_egress_fqdns: builtins.list[str] | None | Unset = UNSET,
+        flavor: RunnerFlavorDto | None | Unset = UNSET,
+        max_runners: int | None | Unset = UNSET,
+        min_runners: int | None | Unset = UNSET,
+        runner_group: str | None | Unset = UNSET,
+        runner_image: str | None | Unset = UNSET,
+        runs_on: str | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Create a `GithubRunner` pool CR for this harbor.
+
+        Validates that the referenced `GithubConnection` exists before creating the
+        CR (fail fast in the UI rather than at reconcile time). Returns 201; 409 if
+        a pool with that name already exists.
+
+        :param connection: Name of the `GithubConnection` holding the credential (as returned by the connections API — the leaf name, not the full secret path).
+        :param extra_egress_fqdns: Extra destinations the pool's network policy allows egress to, beyond the built-in GitHub Actions preset. `host` opens 443/TCP; `host:port` opens that port instead (`deb.debian.org:80`, `registry.corp.example:5000`).
+        :param max_runners: Ceiling on concurrent runners. Defaults to 3.
+        :param min_runners: Warm runners kept idle. Defaults to 0 (scale-to-zero).
+        :param name: Pool name — must be a valid DNS-1123 label, at most 45 characters (GitHub's runner scale-set name limit). The value workflows put in `runs-on:` is the registered scale-set name the operator derives from it and reports back as `status.runner_scale_set_name`.
+        :param runner_group: GitHub runner group (org scope only). Defaults to GitHub's default group.
+        :param runner_image: Runner container image override. Defaults to the platform-pinned `ghcr.io/actions/actions-runner` release.
+        :param runs_on: The name this pool registers under with GitHub — **the value workflows put in `runs-on:`**, and the only thing GitHub schedules a job on for a runner scale set.  Absent (or empty) keeps the name Hyperfluid derives, `<name>-<digest>`, which is unique across the GitHub org by construction. Setting it trades that for a name you choose (`ubuntu-latest`, `hyperfluid-linux-l`, …); the request is rejected with a 409 if another pool on the same GitHub target and runner group already claims it."""
+        response = self._request(
+            ApiRequest(
+                method="post",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                },
+                json_body=to_json_value(
+                    CreateGithubRunnerRequest(
+                        connection=connection,
+                        egress_mode=t.cast(
+                            "GithubRunnerEgressModeDto | None | Unset", egress_mode
+                        ),
+                        extra_egress_fqdns=extra_egress_fqdns,
+                        flavor=flavor,
+                        max_runners=max_runners,
+                        min_runners=min_runners,
+                        name=name,
+                        runner_group=runner_group,
+                        runner_image=runner_image,
+                        runs_on=runs_on,
+                        scope=scope,
+                    ),
+                    CreateGithubRunnerRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+    def retrieve(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Get a single `GithubRunner` pool CR by name (status polling)."""
+        response = self._request(
+            ApiRequest(
+                method="get",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+    def delete(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> None:
+        """Delete a `GithubRunner` pool CR by name.
+
+        Idempotent: 204 even when already absent. The operator's finalizer tears
+        down the `AutoscalingRunnerSet` (ARC deregisters the scale set from
+        GitHub), the config secret, and the network policy via ownerReference GC.
+
+        The 204 is held until the CR is observed gone (bounded — see
+        [`DELETE_SETTLE_BUDGET`]). `Api::delete` only *marks* a finalized object,
+        so returning on its acknowledgement made the client's post-delete refetch
+        race the finalizer and re-render the pool it had just deleted."""
+        self._request(
+            ApiRequest(
+                method="delete",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+
+    def update(
+        self,
+        organization_id: UUID,
+        harbor_id: UUID,
+        name: str,
+        *,
+        connection: str | None | Unset = UNSET,
+        egress_mode: GithubRunnerEgressModeDto
+        | GithubRunnerEgressModeDtoLiteral
+        | None
+        | Unset = UNSET,
+        extra_egress_fqdns: builtins.list[str] | None | Unset = UNSET,
+        flavor: RunnerFlavorDto | None | Unset = UNSET,
+        max_runners: int | None | Unset = UNSET,
+        min_runners: int | None | Unset = UNSET,
+        runner_group: str | None | Unset = UNSET,
+        runner_image: str | None | Unset = UNSET,
+        runs_on: str | None | Unset = UNSET,
+        scope: GithubRunnerScope | None | Unset = UNSET,
+        extra_headers: t.Mapping[str, str] | None = None,
+        extra_query: t.Mapping[str, object] | None = None,
+        extra_body: t.Mapping[str, object] | None = None,
+        timeout: Timeout | Unset = UNSET,
+        max_retries: int | None = None,
+    ) -> GithubRunnerResponse:
+        """Edit a `GithubRunner` pool in place.
+
+        Exists because the alternative — delete and recreate — deregisters the scale
+        set from GitHub, which drops the `runs-on:` target and interrupts whatever
+        was running. Every field below can change without that happening.
+
+        ## What the operator does with each field
+        - **`min_runners` / `max_runners`** — a live resize. ARC moves the target
+          count on the existing `AutoscalingRunnerSet`; no pod is recreated and no
+          running job is touched.
+        - **`flavor` / `runner_image`** — a template change. The runner pod spec is
+          rewritten, so jobs already executing finish on the old template and the
+          next ones start on the new one. Nothing is killed mid-job.
+        - **`runner_group`** — re-registers the scale set into another GitHub runner
+          group. Brief, and the scale-set name is unchanged, so `runs-on:` keeps
+          working.
+        - **`runs_on`** — deregisters the scale set and registers it again under a
+          new name. The one edit here that workflows can see, and the one with
+          downtime: GitHub will not move a registration's runner label in place, so
+          the `AutoscalingRunnerSet` is deleted and re-applied (its Kubernetes name
+          is unchanged, as is every other object). ARC drains in-flight runners
+          first, so no job is killed, but the pool accepts nothing until the new
+          registration is live, and a workflow still naming the old value queues
+          until it is updated. `""` hands the name back to the derived one.
+        - **`extra_egress_fqdns`** — the pool's network policy is re-rendered. It
+          replaces the previous list wholesale rather than merging into it. Entries
+          are `host` (443/TCP) or `host:port`.
+        - **`egress_mode`** — the pool's network policy is re-rendered, in place and
+          without recreating a pod. Cilium applies the new policy to the live
+          endpoints, so a job already running keeps its established connections and
+          only its *next* connect is judged by the new posture.
+        - **`connection`** — the pool's config secret is re-projected from the new
+          credential. This is the rotation path: swap in a fresh App key or PAT
+          without the scale set ever leaving GitHub.
+
+        `scope` is deliberately not editable; see [`UpdateGithubRunnerRequest`].
+
+        :param connection: Move the pool to a different `GithubConnection` — the leaf name, same value `CreateGithubRunnerRequest.connection` takes. Used to swap in a rotated credential without deregistering the scale set. The new connection must point at the same GitHub host as the current one.
+        :param extra_egress_fqdns: Replacement egress allow-list (it replaces the previous one wholesale, it is not merged entry by entry). Send `[]` to keep only the built-in GitHub Actions preset. Entries are `host` (443/TCP) or `host:port`.
+        :param max_runners: New concurrency ceiling. Live resize, same as `min_runners`.
+        :param min_runners: New warm-runner floor. Live resize — ARC changes the target without recreating pods.
+        :param runner_group: New GitHub runner group (org scope only). Send `""` to fall back to GitHub's default group.
+        :param runner_image: New runner container image. Rolls the runner template, same as `flavor`. Send `""` to go back to the platform-pinned default.
+        :param runs_on: New `runs-on:` name. Send `""` to go back to the name Hyperfluid derives from the pool name.  Unlike every other field here this one is **not** transparent to running workflows: the scale set is deregistered and registered again under the new name, so a workflow still saying `runs-on: <old name>` queues until it is edited.  It is also the only edit with downtime. GitHub will not move a registration's runner label in place, so the `AutoscalingRunnerSet` is deleted and re-applied (under its unchanged Kubernetes name). ARC drains in-flight runners first — no job is killed — but the pool accepts nothing until the new registration is live. `status.message` names the old value to keep using meanwhile."""
+        response = self._request(
+            ApiRequest(
+                method="patch",
+                path="/api/v1/organizations/{organization_id}/harbors/{harbor_id}/github-runners/{name}",
+                path_params={
+                    "organization_id": encode_path_param(
+                        "organization_id", organization_id, "simple", False
+                    ),
+                    "harbor_id": encode_path_param(
+                        "harbor_id", harbor_id, "simple", False
+                    ),
+                    "name": name,
+                },
+                json_body=to_json_value(
+                    UpdateGithubRunnerRequest(
+                        connection=connection,
+                        egress_mode=t.cast(
+                            "GithubRunnerEgressModeDto | None | Unset", egress_mode
+                        ),
+                        extra_egress_fqdns=extra_egress_fqdns,
+                        flavor=flavor,
+                        max_runners=max_runners,
+                        min_runners=min_runners,
+                        runner_group=runner_group,
+                        runner_image=runner_image,
+                        runs_on=runs_on,
+                        scope=scope,
+                    ),
+                    UpdateGithubRunnerRequest,
+                ),
+                error_types={
+                    "default": _models.ApiErrorBody,
+                },
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+        )
+        return decode_response(response, GithubRunnerResponse)
+
+
+class GitHubRunnersWithRawResponse:
+    """The methods of :class:`GitHubRunners`, returning an :class:`APIResponse`."""
+
+    def __init__(self, resource: GitHubRunners) -> None:
+        self.list_organization_github_connections = to_raw_response_wrapper(
+            resource.list_organization_github_connections
+        )
+        self.create_organization_github_connection = to_raw_response_wrapper(
+            resource.create_organization_github_connection
+        )
+        self.update_organization_github_connection = to_raw_response_wrapper(
+            resource.update_organization_github_connection
+        )
+        self.delete_organization_github_connection = to_raw_response_wrapper(
+            resource.delete_organization_github_connection
+        )
+        self.list_organization_github_connection_targets = to_raw_response_wrapper(
+            resource.list_organization_github_connection_targets
+        )
+        self.list = to_raw_response_wrapper(resource.list)
+        self.create = to_raw_response_wrapper(resource.create)
+        self.retrieve = to_raw_response_wrapper(resource.retrieve)
+        self.delete = to_raw_response_wrapper(resource.delete)
+        self.update = to_raw_response_wrapper(resource.update)