nsheaps/github-actions — GitHub App Setup

GitHub App Setup

Builds a GitHub App manifest for one of the apps below, walks through registration on github.com, and exchanges the manifest code for the new App's credentials client-side.

App created — exchanging code for credentials…

✓ App credentials

Save these to repository or organization secrets. The private key in particular cannot be retrieved again — generate a new one if you lose it.

App ID → secret Private key (PEM) → secret Webhook secret (unused — store anyway)

App page on GitHub:

Next steps

Something went wrong

Detailed setup walkthrough

What's a GitHub App manifest, and what does the page do?

The page builds a JSON manifest declaring the new app's name, redirect URL, default permissions, and webhook events — then POSTs it to github.com/organizations/<org>/settings/apps/new. GitHub creates the app and redirects back to this page with a temporary code. The page then calls POST https://api.github.com/app-manifests/<code>/conversions from your browser to retrieve the new app's ID, private key, and webhook secret.

Reference: Registering a GitHub App from a manifest.

How do I host this page so it works as the redirect URL?

For nsheaps repos this page is auto-deployed via GitHub Pages from nsheaps/github-actions/pages/. For your own host:

cp pages/index.html docs/index.html
# Settings → Pages → Source: GitHub Actions (or branch /docs)

Then use https://<your-org>.github.io/<repo>/ as the redirect. Any other HTTPS static host (Vercel, Netlify, etc.) works equally well.

I get "Manifest is invalid" from GitHub after clicking the button

Open DevTools, find the manifest payload in the form before submission, and validate it against GitHub's manifest schema. Common gotchas:

url and redirect_url must be HTTPS.
App name must be unique on github.com — try a more specific name.
If the org is restricted to specific apps, the org owner has to approve creation.

I lost the code. Can I get the private key again?

No — GitHub only shows the private key once via the manifest exchange. Regenerate one from the app settings: Private keys → Generate a private key. The old key is invalidated; update the secret.

Manual install (no manifest flow)

Go to Org Settings → Developer settings → GitHub Apps → New GitHub App.
Name it (anything globally unique). Homepage URL: https://github.com/<org> works.
Uncheck "Active" under Webhook unless your preset needs webhooks.
Set permissions matching the preset's What permissions does this app grant? section.
Where can this be installed: Only on this account (or Any account if shareable).
Create. Note the App ID, generate a private key.
Install it on the repos you want to manage.

How do query-param prefills work?

Any form field on this page can be prefilled by appending matching query parameters to the URL. Field names are listed under each input.

Examples:

?preset=apply-repo-settings — selects a preset
?preset=apply-repo-settings&org=nsheaps&appname=my-settings-app — selects preset + prefills org + name
?redirect=https://example.com/cb — overrides redirect URL

The mechanism is generic: every <input> / <select> / <textarea> with a name attribute is candidate. Adding new fields later auto-supports the same prefill pattern.