opschain admin github-connections
integrations:github
Manage the GitHub App connections the GitHub integration trusts. A
connection registers one GitHub App for one GitHub instance —
github.com (the default, GitHub Enterprise Cloud and EMU orgs
included) or a GitHub Enterprise Server host — and anchors everything
the integration does: the trust policies the Actions OIDC token
exchange decides against hang off a connection, and the exchange
verifies presented workflow tokens against the instance's own OIDC
issuer and the connection's expected audience.
The custody posture is reference-first: the record stores
private_key_ref, a secret-vault:// address, never the key itself.
Supply a reference with --private-key-ref — it is resolved when it is
set, so a record can never point at a reference that does not resolve —
or supply the App's PEM key via --private-key-file,
--private-key-env or --private-key-prompt (never on the command
line) and the server holds it encrypted at rest on the record itself
(never in a vault; private_key_ref stays empty and private_key_set
reports it). No read, audit row or error ever returns key material.
Creating or enabling a connection requires the integrations:github
entitlement. Registering a host other than github.com additionally
counts against the self-hosted instance limit — 0 on the Basic tier, so
GitHub Enterprise Server is an Enterprise (or trial-licence)
conversation, while github.com stays Basic-reachable. On licence lapse
stored connections are retained and only new registrations, enabling
writes and token exchanges refuse — everything lights back up on
upgrade.
| Subcommand | Purpose |
|---|---|
list | Every connection: host, key reference, enabled state, health. |
show <code-or-id> | One connection's record. |
create <code> | Register a connection (reference pinned, or inline PEM key vaulted). |
update <code-or-id> | Change fields; a supplied key or reference re-pins. |
delete <code-or-id> | Remove a connection and its trust policies. |
test <code-or-id> | Validate the record without calling GitHub. |
provision-webhook <code-or-id> | Provision GitHub webhook ingestion on the signed inbound lane (/api/hooks/github-<code>). |
Every verb rides the v2 GitHubIntegrationService, which authenticates
user tokens only: the caller's own opschain login session is the
primary credential. An explicit --auth-token wins, and
OPSCHAIN_ADMIN_TOKEN / the opschain admin login token remain the
fallback for automation; the server still requires the /admin
updatable determination.
Exit codes: 0 on success, 1 when a call fails or the token is rejected, 2 for usage errors.
See also
opschain docs cli/admin-github-trust-policies— the policies the exchange decides against.opschain docs integrations-github— the integration end to end.