Skip to main content

@playrunner/github

GitHub Integration

Connect GitHub repositories and install app credentials for Playrunner workflows that need repository access.

View on npmnpm install @playrunner/github
OAuthAPI routesRepository access
Node typeTrigger
Connectionintegration / github
Backend mount/api/github
Frontend

Settings and registration

Exports githubIntegration and GithubSettingsModal. The integration keeps the existing github id so saved workflow auth references continue to resolve.

Backend

OAuth proxy routes

Exports githubRouter, mounted by the host API at /api/github, for token exchange, refresh, repository discovery, and branch discovery.

Used by Playwright

Repository auth

Playwright reuses GithubSettingsModal for repository authentication, so GitHub must remain a selected direct dependency when Playwright is installed.

Assets

Package-owned icon

GitHub exports a package-owned React SVG component that uses currentColor to follow the active theme. Its raw SVG remains available as a separate asset export.

Setup​

For the end-user setup flow, including the GitHub App fields, callback URL, app installation, and repository selection, see Connect GitHub.

Exports​

import githubIntegration, {
  GithubIcon,
  GithubSettingsModal,
  githubIconUrl,
} from '@playrunner/github';
import githubApiContribution, { githubRouter } from '@playrunner/github/api';

Frontend​

The integration uses @playrunner/integration-sdk for host-provided auth, persistence, and UI primitives. Its own package manifest declares the . frontend and ./api surfaces, and each entrypoint default-exports its contribution. Frontend and API builds discover those surfaces from installed direct production dependencies and generate static imports; no shared registry edit is required.

API​

The API entrypoint default-exports githubApiContribution, containing githubRouter and its /api/github mount path.

The router owns:

  • POST /token
  • POST /refresh
  • GET /repositories
  • GET /branches?repository=owner/name

The token endpoint completes the GitHub App installation and user OAuth flow, then saves app metadata and encrypted credentials through the host's request-scoped connection store. The refresh endpoint resolves and updates those secrets on the server. Neither route returns tokens to the browser.

The repository endpoint uses the installation ID saved in connection config and the decrypted user access token from connection secrets. It returns only repository IDs and full names. The branch endpoint accepts the selected owner/name repository and returns branch names. These routes keep GitHub credentials out of browser integration data while still supporting the Playwright selectors.

Assets​

The GitHub SVG lives inside the package at packages/github/assets/github.svg. Product UI renders GithubIcon, whose inline SVG uses fill="currentColor" so the mark follows the active theme. The separate githubIconUrl export is available to consumers that specifically need the asset URL. The app does not need a duplicate public asset or a CSS mask.