opschain admin github-connections create

integrations:github

Registers a GitHub App connection. The code and the host are immutable after create — a different instance is a different registration; everything else can change through the update verb. Creating a connection requires the integrations:github entitlement — the typed FEATURE_ENTITLEMENT_REQUIRED refusal names it — and a host other than github.com additionally sits behind the self-hosted instance limit (0 on Basic: GitHub Enterprise Server needs an Enterprise or trial licence, named in the refusal).

The App private key rides exactly one of two channels, and the record only ever stores a reference:

• --private-key-ref secret-vault://<path>/<key> pins an existing vault reference. The reference is resolved as it is set — pinning a reference that does not resolve refuses by name. A provider-qualified reference (secret-vault://<provider>@<path>/<key>) must name an enabled secrets provider and keeps the key in that customer vault.
• --private-key-file / --private-key-env / --private-key-prompt supply the PEM key inline (never on the command line). The server holds it encrypted at rest on the record itself (never in a vault; private_key_ref stays empty).

opschain admin github-connections create corp-github \
  --app-id 4242 --private-key-file ~/Downloads/opschain-app.pem
Created GitHub connection corp-github for github.com (private_key_ref secret-vault://github-connections/corp-github/credential)

Set --oidc-audience to your server's external URL so a workflow token requested for this instance can never exchange on another; the workflow's setup step must request its OIDC token with the same audience value.

--allowed-repositories and --allowed-permissions bound what a github-app://<code> property reference may ask a just-in-time installation-token mint for: repository names within the installation's account, and name:level permission pairs (read, write or admin). A reference asking beyond the set fails its step by name; a reference asking for nothing on a bounded connection mints exactly the allowed set. Leave both empty for the installation's own grant to be the bound.

opschain admin github-connections create corp-github \
  --app-id 4242 --installation-id 99 --private-key-file ~/Downloads/opschain-app.pem \
  --allowed-repositories payments,ledger --allowed-permissions contents:write,pull_requests:read

Flags

Flag	Meaning
--server <url>	Server base URL (default: the active context / OPSCHAIN_SERVER).
--auth-token <token>	Admin bearer token override (default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login).
--display-name <name>	Human-readable connection name.
--host <host>	GitHub instance host: github.com (the default) or a GitHub Enterprise Server host (Enterprise-gated). Immutable.
--app-id <id>	The GitHub App's numeric id on that instance.
--installation-id <id>	The App installation id just-in-time GH_TOKEN minting mints installation tokens for (0: unset — minting refuses by name until it is recorded).
--oidc-audience <aud>	The aud claim the token exchange requires on presented Actions OIDC tokens (default opschain).
--private-key-ref <ref>	secret-vault:// reference to pin (mutually exclusive with the inline key flags).
--enabled	Whether the connection serves trust policies and token exchanges (default true).
--allowed-repositories <names>	Repository names (within the installation's account, comma-separated) a github-app:// reference may mint for; empty: unrestricted.
--allowed-permissions <pairs>	Permissions a github-app:// reference may mint with, as name:level pairs (read, write or admin), e.g. contents:write,pull_requests:read; empty: unrestricted.
--private-key-file <path>	Path to a PEM file holding the App's private key (the .pem GitHub issues for the App).
--private-key-env <name>	Environment variable holding the App's PEM private key (never the value itself on argv).
--private-key-prompt	Prompt for the App's PEM private key without echo.

See also

• opschain docs cli/admin-github-trust-policies-create — declaring who may exchange.