Skip to main content
The hosted service has an app already. If you run your own control plane, you create one. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.

​
URLs

Leave “Request user authorization (OAuth) during installation” off, and uncheck “Expire user authorization tokens” only if you have a reason to.
For local development, expose the API with a tunnel and use the tunnel’s URL as PUBLIC_URL:

​
Permissions

Each one maps to something specific. Nothing here grants access to your Actions secrets, which GitHub does not expose to apps at all.

​
Repository permissions

​
Organization permissions

The two optional write permissions are used for exactly one thing: the access-control API opening a pull request against your .airship repository. Without them, everything else works and you edit access.yaml yourself.

​
Events to subscribe to

Missing Workflow job means nothing ever launches. Missing Push means pool changes are picked up late. Missing Repository means a renamed repository drifts until it is re-read.

​
After creating it

Collect these and put them in the API’s environment:
The PEM can be the variable itself — with real newlines, or on one line with literal \n — or a mounted file. See Configuration.

​
GitHub Enterprise Server

Point the API at your instance:
Create the app in your instance’s own developer settings. Everything else is the same.

​
Checking it works

1

Sign in

Open the dashboard and sign in with GitHub. A failure here is almost always the callback URL or the client secret.
2

Install it on an organization

Grant it one repository. The installation should appear in the dashboard immediately.
3

Watch a webhook arrive

Push a workflow that uses an airship- label. The job should appear on Jobs within a second or two.If it does not, GitHub’s Advanced tab on the app shows each delivery and its response. A 401 there means the webhook secret does not match.

​
Uninstalling

Uninstalling the app finishes every runner with reason deleted and destroys its machine. The installation record is kept so machines still running in a connected cloud can be torn down.