livery.forge._github¶
livery.forge._github ¶
The GitHub backend: livery.forge.Forge over REST v3 plus one GraphQL pair.
REST carries everything except auto-merge, which GitHub exposes only
as the GraphQL mutations enablePullRequestAutoMerge and
disablePullRequestAutoMerge.
Construction and the token rule: livery.forge.GithubForge.connect
resolves the server once (github.com unless a GitHub Enterprise URL is
given) and the token as GITHUB_TOKEN first, then gh auth token,
so a machine with a signed-in gh CLI needs no configuration. The token
belongs to the resolved host and no other.
Capabilities: auto_merge, force_cancel, required_contexts,
schedule_events, and min_approvals are supported.
ci_secrets depends on the
github-secrets extra: the secrets API demands sealed-box
encryption (libsodium), which PyNaCl provides and the standard
library cannot, so livery-forge[github-secrets] turns the
capability on and a bare install declines it by name. The import is
lazy; nothing outside the secrets path ever loads it.
Classes:
| Name | Description |
|---|---|
GithubForge |
One GitHub server, spoken to through livery.forge.Forge's verbs. |
GithubForge ¶
One GitHub server, spoken to through livery.forge.Forge's verbs.
Build with livery.forge.GithubForge.connect; the constructor takes the resolved values and applies no environment fallbacks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_base
|
str
|
The API root: |
required |
token
|
str
|
The token sent on every request. |
required |
opener
|
Opener | None
|
The network seam; the redirect-refusing default when omitted. |
None
|
Bind the client to api_base with token.
Methods:
| Name | Description |
|---|---|
connect |
The server, resolved once, never inferred from ambient state. |
whoami |
The authenticated user's login name ( |
server_version |
The Enterprise version from |
registry_url |
GitHub hosts a container registry; the others decline. |
supports |
Honest per-install: |
repository |
The view onto one repository. Cheap, no network. |
members |
The org's member logins; a user namespace is its one login. |
teams |
The org's team slugs; a user namespace has none. |
codeowners |
GitHub's dialect: |
user_url |
The address of login's profile; nothing on the wire. |
create_repo |
Create the repository under an org or the token's own user. |
get_repo |
The repository's settings, or None when it does not exist. |
delete_repo |
Delete the repository; one already gone is success. |
graphql |
One GraphQL call; errors raise with GitHub's words verbatim. |
Attributes:
| Name | Type | Description |
|---|---|---|
token |
str
|
The credential this connection authenticates with; empty when anonymous. |
Source code in packages/forge/src/livery/forge/_github.py
token
property
¶
token: str
The credential this connection authenticates with; empty when anonymous.
connect
classmethod
¶
connect(*, url: str = '', token: str | None = None, opener: Opener | None = None) -> GithubForge
The server, resolved once, never inferred from ambient state.
github.com unless url names a GitHub Enterprise server (its
API is at <url>/api/v3). token resolves as
GITHUB_TOKEN first, then gh auth token; nothing found
raises, because an unauthenticated write fails later and
further from the cause. Pass token="" to read anonymously
on purpose.
Source code in packages/forge/src/livery/forge/_github.py
server_version ¶
server_version() -> str
The Enterprise version from GET /meta, or github.com.
github.com carries no version; the constant string satisfies the protocol's non-empty answer and names the host class.
Source code in packages/forge/src/livery/forge/_github.py
registry_url ¶
registry_url(kind: RegistryKind, owner: str) -> str
GitHub hosts a container registry; the others decline.
container answers the ghcr prefix on github.com (an
enterprise install's registry host is not derivable from the
API base, so it declines there too, and the contract's own
declaration is the path). python declines: GitHub hosts
no python index, and pypi.org is the resolution ladder's
ecosystem default, not this forge's registry. conan
declines: GitHub has no conan registry at all.
Source code in packages/forge/src/livery/forge/_github.py
supports ¶
supports(capability: Capability) -> bool
Honest per-install: ci_secrets needs the extra installed.
Source code in packages/forge/src/livery/forge/_github.py
repository ¶
repository(owner: str, name: str) -> Repository
members ¶
The org's member logins; a user namespace is its one login.
Source code in packages/forge/src/livery/forge/_github.py
teams ¶
The org's team slugs; a user namespace has none.
Source code in packages/forge/src/livery/forge/_github.py
codeowners ¶
codeowners(entries: tuple[CodeownersEntry, ...]) -> Codeowners
GitHub's dialect: .github/CODEOWNERS, @owner lines.
A per-path approval count has no spelling here; protection approximates it repository-wide, and the note says so.
Source code in packages/forge/src/livery/forge/_github.py
user_url ¶
create_repo ¶
create_repo(owner: str, name: str, *, private: bool = True, description: str = '') -> Repository
Create the repository under an org or the token's own user.
auto_init gives it the default branch the protocol
requires.
Source code in packages/forge/src/livery/forge/_github.py
get_repo ¶
The repository's settings, or None when it does not exist.
Source code in packages/forge/src/livery/forge/_github.py
delete_repo ¶
Delete the repository; one already gone is success.
The token needs the delete_repo scope; a 403 quotes
GitHub's refusal verbatim.
Source code in packages/forge/src/livery/forge/_github.py
graphql ¶
One GraphQL call; errors raise with GitHub's words verbatim.
GraphQL failures answer 200 with an errors array, so the
HTTP layer cannot see them; this is where they become
livery.forge.ForgeError.