The GitHub App

A repository source is not a URL somebody types in. Aerie reaches GitHub through a GitHub App, and a project builds a repository that a live installation of that app can see.

Three things fall out of that, and all three are the point.

Only public repositories are built#

Visibility is read from GitHub at connect time, again before every build — the one the console starts and the one a push starts — and again whenever GitHub sends a repository event.

A repository that goes private stops building the moment the event lands, and the source says so on the Flight page.

Recovering is one button. Make the repository public again and press re-check on the Flight page.

The installation is bound to your account#

The install flow carries a state token the console issued, and the callback is accepted only after GitHub's user authorization confirms the same person owns that installation.

The repository picker only ever lists installations you own, and it reads what they can see live from GitHub rather than from a cache.

There is one webhook#

On the app, not per project. No per-project URL, no per-project secret to copy or rotate.

The signature header is verified against the app's webhook secret before the body is read, and events are routed on the repository id.

An event for an archived project is acknowledged and ignored. So is an event this console does not recognise, because GitHub retries anything that is not a 200.

Permissions the app asks for#

There is no contents permission and no access to issues, actions or secrets. The two write permissions write nothing but a build's own deployment and status: neither can reach the code, and neither is used while no build is running.

What a build looks like on GitHub#

Every build a repository source starts is reported back to GitHub twice over, the way a hosting provider reports one.

A deployment is opened against the commit as soon as the build is queued, in a production/<project> environment, and it moves through queued, in_progress and then success or failure. A successful deployment links to the program's page on Roost, so the repository's Deployments page is a way into the published program. Every deployment also carries a log link back to the build in the console.

A commit status is posted under the ceagle/flight/<project> context against the same commit. It is pending while the build is queued and running, and it settles to success or failure. A successful status links to the program on Roost, and a failed one links to the build page that says why.

Both names carry the project id, because GitHub keys a deployment by its environment and a commit status by its context. A repository that backs more than one project therefore gets one deployment and one status per project on the same commit, instead of each project erasing the other's result.

GitHub is told about a build, never asked. A build is never held up, failed or retried because GitHub was unreachable, and an upload project never reaches GitHub at all.

Managing what it can see#

Which repositories the app can reach is decided on GitHub, not in the console.

1. Open the installation on GitHub

   The Flight page links straight to it, and so does each installation in the repository picker.

2. Grant or revoke repositories

   Either all repositories, or a chosen list. The console never sees anything outside that list.

3. Refresh the installation

   Back in the console, so the repository list is re-read from GitHub rather than from a cache.

Uninstalling#

Removing the app from an account ends every source that reached repositories through it. The projects, their addresses and everything already published stay exactly as they were, so reinstalling and reconnecting brings builds back.