Connect GitHub with a GitHub App

What the GitHub App is for

In the portal: Setup wizard, the Code step, or Admin, Settings, Code and repositories

It is optional, and the one optional step worth doing. With a GitHub App cyantula can clone private repositories, let every colleague pick from their own repositories, open changes as pull requests, and create a repository for a brand-new app. Without it you can still publish public repositories, zips and single HTML pages.

You make one App for your cyantula, owned by a GitHub organisation (not a personal account): that organisation is also where new app repositories are created.

The quick way: the prompt

The Code step shows a prompt with your server's addresses already filled in. Paste it into a coding agent that can use the GitHub CLI and a browser (Claude Code, for example). It creates the App, installs it on your organisation and hands back the values for the fields. You approve one page on GitHub along the way.

By hand

1. On GitHub, open your organisation's Settings, Developer settings, GitHub Apps, New GitHub App. See GitHub's guide.
2. Homepage URL: your portal. Callback URL: https://<your portal>/auth/github/callback. Tick Request user authorization (OAuth) during installation. Leave user token expiry on.
3. Repository permissions:
   • Administration: Read and write (to create repositories)
   • Contents: Read and write
   • Issues: Read and write
   • Pull requests: Read and write
   • Webhooks: Read and write
   • Metadata: Read-only
4. Where can it be installed: Any account, so colleagues can install it on repositories of their own too.
5. Create it. On its page, copy the App ID, the Client ID and the app's URL name (the slug, the last part of github.com/apps/<slug>). Generate a client secret and a private key; the key downloads as a .pem file.
6. Install the App on your organisation (github.com/apps/<slug>/installations/new), on all repositories or the ones cyantula should manage.

What goes where

• GitHub organisation for new repositories: the organisation login.
• GitHub App ID, client ID, client secret and slug: from the App's page.
• GitHub App private key (PEM): the whole .pem file, BEGIN and END lines included.

After saving, the check on the same page tells you whether GitHub accepts the App and where it is installed.

No App possible? Under Advanced, a fine-grained, read-only GitHub personal access token lets cyantula clone private repositories. It cannot open pull requests or create repositories.