Skip to content

guides

Intended Documentation

GitHub Connector Setup (Beta)

Connect Intended to GitHub for workflow dispatch and PR creation. GitHub authenticates as a GitHub App via the install flow — not per-tenant credentials typed into the console. Host-pinned to api.github.com. Beta until validated against a live installation.

intermediate3 min readpartial
PartialSource: codeValidated: 2026-07-09

GitHub Connector Setup (Beta)#

Connect Intended to GitHub so approved intents can dispatch Actions workflows and open pull requests through the real GitHub adapters (packages/execution-engine/src/adapters/github-actions.ts, github-pr.ts). Every write is Authority-Token-verified and ESCALATEs for approval under the starter policy.

This connector is Beta

The adapters are real and covered by hermetic (mocked-HTTP) tests that pass in CI with no live tenant. Live proof against an external customer installation is pending — treat GitHub as Beta. See the Capability Truth Matrix.

GitHub is different — no credential fields#

No secrets are typed into the console for GitHub

Unlike every other connector, GitHub authenticates as a GitHub App through the install flow, using server-side app config (GITHUB_APP_ID + the app private key) and a per-tenant installation mapping keyed by owner/repo. The adapter reads no per-tenant credential from the connect dialog — so the connect wizard presents no credential fields for GitHub. You connect GitHub by installing the Intended GitHub App, not by pasting a token.

What the adapters do#

PropertyValue
Actionsgithub.workflow.dispatch, github.pr.create
AuthGitHub App installation token — Authorization: Bearer <installation-token> (X-GitHub-Api-Version: 2022-11-28)
Pinned hostapi.github.com (HTTPS-only; the Actions adapter enforces hostname === "api.github.com")
Test connection (Actions)App JWT → GET /app
Test connection (PRs)Verifies the server-side App config is present (GITHUB_APP_ID + private key)

Endpoints: workflow dispatch → POST /repos/{owner}/{repo}/actions/workflows/{workflowId}/dispatches (expects 204); PR create → POST /repos/{owner}/{repo}/pulls (expects 201).

How to connect (install flow)#

  1. In the Console Connectors view, choose GitHub. Because there are no credential fields, the Configure-auth step shows that GitHub authenticates via a server-side app installation.
  2. Use the Install GitHub App flow to install the Intended GitHub App on the target organization/account and select the repositories Intended may act on. This creates the per-tenant installation mapping the adapters use.
  3. Grant the App only the least-privilege permissions below during installation.

Least-privilege scope guidance#

  • Matrix scopes: actions:write (workflow dispatch), pull_requests:write (PR create).
  • On the GitHub App's repository permissions, grant:
    • Actions: Read and write — for github.workflow.dispatch.
    • Pull requests: Read and write — for github.pr.create.
    • Contents: Read (and Write only if your PR head branches are created by the App).
  • Install the App on only the repositories Intended needs — not "All repositories" unless required.

Fields to paste into the connect dialog#

None. GitHub has no credential fields in the connect wizard. Authentication is the GitHub App installation described above; the app's app_id, private key, and installation_id are managed server-side, not entered per tenant.

Verify the connection#

  • Actions adapter: Test connection mints an App JWT and calls GET /app; a green result means the App config and installation resolve.
  • PR adapter: Test connection checks that the server-side App config (GITHUB_APP_ID + private key) is present.

If Test connection fails with GITHUB_APP_CONFIG_MISSING, the server-side GitHub App is not configured — that is an operator/platform action, not a per-tenant credential you can paste.

Next steps#

GitHub Connector Setup (Beta) | Intended