Connecting GitHub to Forge

Forge talks to GitHub through the Balaur Forge GitHub App. Installing it on a repository is what lets Forge clone it when it is private, hear about every push, and put a check on each commit.

Connect and install

1. On Projects or New project, press Connect GitHub. GitHub asks you to authorise Forge once; Forge uses that to ask GitHub which App installations you can see, and nothing else.
2. If the App is not installed anywhere yet, press Install the App. Pick your account or an organisation you administer, and choose All repositories or only the ones Forge should build. GitHub sends you back and your installations appear.
3. On New project → From GitHub, pick the installation, then the repository. The name and default branch are filled in from it; tick the targets and register.

Installing on an organisation needs an owner of that organisation. A member can request the installation, and an owner approves it on GitHub.

A repository is missing from the list? The installation was given selected repositories and that is not one of them. Use Grant the App access to it under the list, add the repository on GitHub, then reconnect.

What the App can see and do

It cannot push, open issues or pull requests, or read repositories you did not grant. Forge decides which installations your account may build from by asking GitHub with your own authorisation, so nobody else can bind a project to your repositories.

Every push builds

Once a project is registered from GitHub, every push to that repository starts a build of the pushed branch or tag, with the project's targets, at the exact commit that was pushed. A project registered by URL builds on push too, if the App is installed on its repository.

Renaming the repository or moving it to another account on GitHub does not break anything: Forge follows the repository by GitHub's id, not its name.

Pushes share your limit of three builds running at once, and a push over it waits: its build and checks show as queued, and it starts on its own when one of the three finishes. Up to ten pushes wait at a time; past that a push is dropped, which only a runaway script pushing in a loop should ever reach.

Checks on the commit

Each target shows on the commit, and on its pull request, as Forge / <target>: queued when the push lands, in progress while it builds, then success with the file's size and digest, or failure with the reason. Details opens the build on Forge with the full output.

Taking access away

• Removing a repository from the installation, or uninstalling the App, stops pushes from building and stops private clones. The projects stay; a private one fails at the clone until access comes back.
• A suspended installation stops everything until it is unsuspended on GitHub.

Both are done on GitHub, under the account's Settings → Applications (or the organisation's Settings → GitHub Apps).