GitHub connection
integrations:github
A GitHub connection is one registered GitHub App against one GitHub
instance (github.com or a GitHub Enterprise Server host): the credential
root the GitHub integration's trust policies, Actions OIDC token exchange,
just-in-time GH_TOKEN minting and webhook ingestion all hang off. The App
private key never rides a read: supplied inline it is held encrypted at
rest on the record; supplied as a reference, only the secret-vault://
address is stored.
Served by the v2 GitHubIntegrationService (ListGitHubConnections,
GetGitHubConnection, CreateGitHubConnection, UpdateGitHubConnection,
DeleteGitHubConnection, TestGitHubConnection,
ProvisionGitHubWebhook).
GitHubConnection
GitHubConnection is one registered GitHub App connection. There is no private-key field on a read: the record carries private_key_ref, a secret-vault:// address (a pointer, not a secret), or holds the inline key encrypted at rest and reports private_key_set.
| Field | Type | Meaning |
|---|---|---|
allowed_scope | GitHubMintScope | The repositories and permissions a github-app:// reference may ask a just-in-time installation-token mint for. Absent: unrestricted — the installation's own grant is the bound. A reference asking beyond the set is refused by name at dispatch; a reference asking for nothing on a bounded connection mints the allowed set. |
app_id | integer/string | The GitHub App's numeric id on that instance. |
code | string | The code the connection is addressed by (trust policies and the exchange reference it). |
created_at | timestamp | When the record was created. |
display_name | string | The connection's display name. |
enabled | boolean | Whether the record is enabled. |
host | string | The GitHub instance host: "github.com" (the default) or a GHES host. Immutable — a different instance is a different registration, and self-hosted hosts sit behind the Enterprise-tier instance limit. |
id | string | The record's identity. |
installation_id | integer/string | The GitHub App installation id JIT GH_TOKEN minting mints installation tokens for (0: unset — JIT minting refuses by name until an administrator records it). |
last_test_at | timestamp | The most recent test verb's outcome (never key material). last_test_at is unset until the first test. |
last_test_error | string | The most recent test's failure message; "" on success (never key material). |
last_test_success | boolean | Whether the most recent TestGitHubConnection succeeded (meaningful once last_test_at is set). |
oidc_audience | string | The aud claim the exchange requires on presented Actions OIDC tokens (the audience the workflow requests its token with). Default "opschain"; set it to the instance's external URL so tokens minted for one OpsChain instance never exchange on another. |
private_key_ref | string | The canonical secret-vault:// reference the App private key lives at. Empty when the key is held encrypted at rest on the record (an inline write clears the reference; a reference write clears the at-rest key). |
private_key_set | boolean | Whether an App private key is held — a pinned reference or an inline key encrypted at rest (the value is write-only). |
updated_at | timestamp | When the record was last updated. |
webhook_connection_code | string | The inbound-webhook connection code GitHub webhook ingestion was provisioned onto (empty until ProvisionGitHubWebhook runs); deliveries POST to /api/hooks/. |
GitHubMintScope
GitHubMintScope narrows a GitHub App installation-token mint: the repository names and the permission → level map GitHub's installation access-token endpoint accepts. Empty members narrow nothing.
| Field | Type | Meaning |
|---|---|---|
permissions | map<string, string> | Permission name → level (read, write or admin), e.g. contents: write. A reference may ask for a named permission at or below the allowed level and nothing the map does not name. |
repositories | string[] | Repository names within the installation's account (never owner/name). |
The same shape rides a property reference as github-app://<code>?repos=a,b&permissions=contents:write,pull_requests:read (opschain docs integrations-github, "Just-in-time GH_TOKEN").
Related pages
opschain docs integrations-github— the component page: the App model, token exchange and webhook ingestion.opschain docs resources/github_trust_policy— the claim predicates deciding the exchange.opschain docs resources/inbound_webhook_connection— where provisioned webhook deliveries land.