From 974e215b6bc3082db765385c1917610523c5fb34 Mon Sep 17 00:00:00 2001 From: trivedi-vatsal Date: Tue, 1 Sep 2026 14:00:30 +0530 Subject: [PATCH] Lead GitHub App setup with Create with GitHub; paste stays under Advanced. Co-authored-by: Cursor --- src/content/docs/setup/github-app.md | 29 ++++++++++++++++++++-------- src/content/docs/start/faq.md | 9 ++++++--- src/content/docs/using/api.md | 2 ++ 3 files changed, 29 insertions(+), 11 deletions(-) diff --git a/src/content/docs/setup/github-app.md b/src/content/docs/setup/github-app.md index 34bd611..a58ab2e 100644 --- a/src/content/docs/setup/github-app.md +++ b/src/content/docs/setup/github-app.md @@ -1,6 +1,6 @@ --- title: "Register a GitHub App" -description: "Register a GitHub App: the permissions, events, and webhook URL openpreflight needs, and why an App is required." +description: "Create a GitHub App with GitHub's review screen, or paste credentials. Permissions, events, and webhook URL." sidebar: order: 1 --- @@ -11,9 +11,25 @@ pipeline and its manifest has no `checks` permission. Coolify is used here for server inventory and as a repository picker; the checks come from an App you register. See [ADR 003](/adr/003-github-app/). -## Create the App on GitHub +Set the **public base URL** in Settings first so GitHub can reach the callback +and the webhook. -GitHub → Settings → Developer settings → **GitHub Apps** → New GitHub App. +## Create with GitHub + +On the **GitHub Apps** page, **Create with GitHub**. GitHub shows a review +screen with the permissions this worker needs (`checks: write`, +`contents: read`, `metadata: read`; Check suite and Check run events). Confirm +it; we store the App ID, slug, PEM, and webhook secret GitHub returns, and +point the webhook at `{public base URL}/webhook/{slug}`. + +The PEM and the webhook secret are encrypted at rest and never shown again. + +This path is github.com only. GitHub Enterprise: paste credentials (below). + +## Advanced — paste credentials + +GitHub → Settings → Developer settings → **GitHub Apps** → New GitHub App, +then paste name, slug, App ID, webhook secret, and PEM. | Setting | Value | |---|---| @@ -23,11 +39,8 @@ GitHub → Settings → Developer settings → **GitHub Apps** → New GitHub Ap | Subscribe to events | Check suite, Check run | Generate a private key, install the App on the account or org that owns the -repos, then add it under **GitHub Apps** in openpreflight: name, slug, App ID, -webhook secret, PEM. Test mints an App JWT and lists installations. - -The PEM and the webhook secret are encrypted at rest and never shown again. -The API returns a redacted marker, not the value. +repos, then add it under **GitHub Apps** in openpreflight. Test mints an App +JWT and lists installations. ## After the App is registered diff --git a/src/content/docs/start/faq.md b/src/content/docs/start/faq.md index d83dd06..c4e811b 100644 --- a/src/content/docs/start/faq.md +++ b/src/content/docs/start/faq.md @@ -48,9 +48,10 @@ See [ADR 005](/adr/005-check-suite-gating/). ## What is deliberately not in v1? -No GitHub Actions YAML, no `actions/runner`, no creating GitHub Apps for you, -no matrices, caches, or artifacts. Jobs on another machine use a Docker -engine via `CI_DOCKER_HOST`, not Coolify's API as a job runner. +No GitHub Actions YAML, no `actions/runner`, no matrices, caches, or +artifacts. Jobs on another machine use a Docker engine via `CI_DOCKER_HOST`, +not Coolify's API as a job runner. A GitHub App can be created with GitHub's +review screen, or pasted. See [Architecture](/understanding/architecture/) and the homepage's "What it isn't" list. @@ -65,6 +66,8 @@ origin is derived from it, so `https://ghe.example.com/api/v3` clones from `https://ghe.example.com`. Nothing else in the request path assumes github.com. +Create with GitHub is github.com only. GitHub Enterprise: paste credentials. + What is untested is everything specific to a GHE deployment: its certificate chain, its API version skew, and Check Runs behaviour on older releases. If you try it, an issue saying which version and what broke is useful. diff --git a/src/content/docs/using/api.md b/src/content/docs/using/api.md index 91bd59b..2aca7ca 100644 --- a/src/content/docs/using/api.md +++ b/src/content/docs/using/api.md @@ -48,6 +48,8 @@ aliases that mirror `PATCH` / `DELETE` for the HTML UI are omitted. |---|---|---| | `GET` | `/api/v1/github-apps` | List Apps | | `POST` | `/api/v1/github-apps` | Create (`{ name, slug, app_id, pem, webhook_secret }`) | +| `POST` | `/api/v1/github-apps/manifest/start` | Start GitHub App manifest (session + CSRF) | +| `GET` | `/api/v1/github-apps/manifest/callback` | Manifest redirect (`code` + `state`) | | `PATCH` | `/api/v1/github-apps/{id}` | Update App | | `POST` | `/api/v1/github-apps/{id}/test` | App JWT + installations | | `GET` | `/api/v1/github-apps/{id}/repos` | Installations + repositories |