Skip to content

v2.0 Wave C: Lead GitHub App setup with Create with GitHub #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trivedi-vatsal merged 1 commit into from
Sep 2, 2026
Merged

v2.0 Wave C: Lead GitHub App setup with Create with GitHub #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions src/content/docs/setup/github-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand All @@ -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 |
|---|---|
Expand All @@ -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

Expand Down
9 changes: 6 additions & 3 deletions src/content/docs/start/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/using/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down