saltext.github.utils.gh.client

Shared plumbing for talking to the GitHub v3 API via PyGithub.

The functions in this package operate on a GitHubConnection and raise GitHubApiError (or its GitHubNotFoundError subclass) on API errors. They are shared between the classic github execution module and future resource modules.

saltext.github.utils.gh.client.get_connection_ident(token, api_url)

Render the internal identity for a (token, api_url) combination. The output is used in context cache keys and persistent cache banks.

token

API token from profile.

api_url

API URL from profile.

saltext.github.utils.gh.client.get_app_connection_ident(app_id, owner, api_url, permissions=None)

Render the internal identity for a GitHub App’s installation on an owner, the app-authenticated counterpart of get_connection_ident(). Derived from the app’s identity rather than its short-lived installation tokens, so it stays stable across token minting/rotation (keeping e.g. persistent cache banks alive between processes).

app_id

App ID (or client ID) from profile.

owner

Owner (organization or user) login the app installation targets.

api_url

API URL from profile.

permissions

Optional permission restrictions the minted tokens are subject to. Profiles restricted differently must not share connections (and thus identities), their tokens are not interchangeable.

saltext.github.utils.gh.client.build_app_auth(app_id, private_key, installation_id, permissions=None)

Return PyGithub auth for a GitHub App installation. It mints installation tokens on demand and refreshes them before expiry.

app_id

App ID (or client ID) of the GitHub App.

private_key

Private key of the GitHub App in PEM format.

installation_id

ID of the app’s installation on the target owner, see resolve_app_installation_id().

permissions

Optional mapping of permission name to access level the minted tokens are restricted to. Defaults to all the app’s granted permissions.

saltext.github.utils.gh.client.resolve_app_installation_id(app_id, private_key, owner, api_url)

Resolve the ID of a GitHub App’s installation on an owner (an organization, falling back to user accounts).

app_id

App ID (or client ID) of the GitHub App.

private_key

Private key of the GitHub App in PEM format.

owner

Owner (organization or user) login the app installation targets.

api_url

Base URL of the GitHub API.

class saltext.github.utils.gh.client.GitHubConnection(auth: dataclasses.InitVar[str | github.Auth.Auth], _owner: str | None = None, *, api_url: str = 'https://api.github.com', cache: dict = <factory>, ident: str = '', store: ~saltext.github.utils.gh.cache.PersistentCache | None = None)

An authenticated PyGithub client bound to a default repository owner (an organization or user), together with caches for API responses.

auth

Personal access token to authenticate with, or a PyGithub Auth instance (e.g. the result of build_app_auth()). Passing the latter requires ident.

owner

Login of the organization or user this connection is scoped to. Organization-scoped operations require this to be an organization. Defaults to the token’s user, which requires a token that is tied to a user account.

api_url

Base URL of the GitHub API. Set this when targeting a GitHub Enterprise Server instance. Defaults to the public GitHub API.

ident

Identity of the connection’s credentials/endpoint, safe to expose (e.g. as a persistent cache namespace). Defaults to get_connection_ident() for token auth; required for Auth instances (whose tokens can be short-lived, see get_app_connection_ident()).

store

Optional PersistentCache for slow-changing API data, surviving across processes.

with_(*, owner: str | None | EllipsisType = Ellipsis, store: PersistentCache | None | EllipsisType = Ellipsis)

Return an instance of this connection with different internal config.

owner

If specified, ensure the returned connection defaults to this owner.

store

If specified, ensure the returned connection uses this persistent store/does not use any.

property owner

Login of the organization or user this connection is scoped to. Defaults to the token’s user (lazily resolved).

property org

PyGithub Organization object this connection is scoped to (cached). The connection’s owner must be an organization.

get_org(owner=None)

Return a PyGithub Organization object for an owner login (cached). Defaults to the connection’s owner.

property auth_user

PyGithub AuthenticatedUser object of the token’s user (cached).

property auth_login

Login of the token’s user (cached, persistently when the connection carries a store).

is_auth_user(login)

Whether a login belongs to the token’s user. Returns False for tokens that are not tied to a user account (e.g. GitHub App installation tokens), whose user lookup fails.

owner_type(owner=None)

Return the account type of an owner login, either Organization or User (cached, persistently when the connection carries a store). Defaults to the connection’s owner.

bind(mod)

Wrap a module to pass the connection as the first positional argument and auto-default the owner param to the one defined on the client when any function is called.

repo_query(owner, *path, **kwargs)

Make a direct call to the /repos GitHub API, defaulting the first following path segment to the configured owner if unspecified. Otherwise delegates to query.

owner

Pass an explicit owner. Defaults to the owner configured for the connection.

Pass an arbitrary number of path segments as string-valued positional args.

query(path, *, params=None, method='GET', headers=None, data=None, per_page=None)

Make a direct call to the GitHub API, transparently following pagination.

path

URL path to query, either as a string or a list of segments.

params

Mapping of query parameters.

method

HTTP method to use. Defaults to GET.

headers

Mapping of extra headers to send.

data

Request body. JSON strings are decoded first.

per_page

Pagination size, maximum 100.

Returns the decoded response data. List results are merged across pages. Raises GitHubNotFoundError for missing resources and GitHubApiError for other error responses.

saltext.github.utils.gh.client.revoke_installation_token(conn)

Revoke the GitHub App installation access token a connection currently authenticates with (would otherwise stay valid for one hour after minting).

The connection – and any others sharing its client – must not be used afterwards: PyGithub only mints a new token once the revoked one would have expired, not in response to auth failures. Callers should evict the connection from their caches, ensuring later invocations build a fresh one.

conn

GitHubConnection to use. Must be app-authenticated.

saltext.github.utils.gh.client.rate_limit(conn)

Return the API rate limit status of a connection’s token, keyed by resource (core, search, …). The deprecated top-level rate alias for core is excluded.

conn

GitHubConnection to use.

saltext.github.utils.gh.client.api_request(func)

Decorator that translates PyGithub exceptions escaping func into GitHubApiError/GitHubNotFoundError, ensuring callers never need to handle PyGithub exception types.