Docs / Integrations

Connect GitHub

Isoward uses two separate GitHub integrations:

  • Sign in with GitHub: OAuth login (optional, env-gated) — callback https://isoward.com/v1/auth/github/callback
  • GitHub App: clones repositories and receives push webhooks for auto-deploy

Where to create the App

Create and own the App under the isoward organization: Organization settings → Developer settings → GitHub Apps. Do not use Third-Party Access / Integrations (that gate is for approving other vendors' apps).

Preferred: open https://isoward.com/v1/setup/github-app (or run GITHUB_APP_ORG=isoward GITHUB_APP_REGISTRATION_TARGET=org node scripts/register-github-app.mjs) while logged in as an org owner — GitHub's Manifest flow pre-fills the same fields and returns the PEM and webhook secret.

Manual form field reference

If you create the App in the UI, use these values (base origin from ISOWARD_PUBLIC_URL):

SettingValue
GitHub App nameIsoward
DescriptionClone repos and receive push webhooks for Isoward auto-deploy.
Homepage URLhttps://isoward.com
Callback URLhttps://isoward.com/v1/github/callback
Request user authorization during installationUnchecked
Setup URL (post-installation)https://isoward.com/v1/github/callback
Redirect on updateChecked — same as Setup URL
Webhook URLhttps://isoward.com/webhook/github
Webhook active / SSLActive; SSL verification enabled
PermissionsMetadata (read), Contents (read), Webhooks (read & write)
Eventspush, pull_request, installation, installation_repositories
Where can this GitHub App be installed?Any account (public App)

Do not use /v1/setup/github-app/callback as the Setup URL — that path is only for one-time Manifest registration when creating the App. End-user installs must land on /v1/github/callback.

After create

  1. Set GITHUB_APP_ID, GITHUB_APP_SLUG (prefer isoward), and the webhook secret as GITHUB_APP_WEBHOOK_SECRET / GITHUB_WEBHOOK_SECRET
  2. Generate a private key → save PEM → mount via GITHUB_APP_PRIVATE_KEY_PATH (or import with ./scripts/import-github-app.sh)
  3. Optionally run node scripts/update-github-app-isoward-urls.mjs to refresh the webhook URL via API
  4. Restart the gateway; smoke Install → repo list → push auto-deploy

Private key rotation

  1. GitHub App settings → Private keys → Generate a private key
  2. Save PEM to server secrets path
  3. Run import script and restart gateway
  4. Verify with GET /v1/github/diagnostics

Dashboard

Integrations → Connect GitHub for deployments. Choose account, org, and repositories. Use Connect another GitHub account for multiple identities.