GitHub App

Why Use the GitHub App

DeployKit can reach a private repository in two ways: an access token pasted into the application (works with GitHub, GitLab, Gitea or any HTTPS git server), or a GitHub App registered on your instance. For github.com the App is the recommended path:

• No long-lived token is stored — each clone uses an installation token that expires after one hour and only sees the repositories you granted
• You pick account → repository → branch from a list instead of pasting a URL
• Pushes and pull requests arrive automatically — there is no per-repository webhook to configure
• Repositories are tracked by their numeric GitHub id, so renaming or transferring a repo does not break auto-deploy
• Every deploy is reported back on the commit as a status, and preview deployments comment their URL on the pull request

Both paths can coexist: applications that are not connected keep using their access token and repository webhook.

Registering the App

Each DeployKit instance owns its own private App (GitHub has to deliver webhooks to your server, so there is no shared central App). Registration uses GitHub's manifest flow — you never copy an App ID or private key by hand. Admin role required.

• Go to Settings → GitHub App and click Set up (or open /settings/github)
• Optionally set an App name (default: "DeployKit - <your host>" — App names are unique across GitHub) and an Organization to create it under; leave it empty for your personal account. Creating it in an organization needs owner rights there
• Click Register on GitHub and confirm the creation on GitHub
• GitHub redirects back to DeployKit, which exchanges the one-time code for the App credentials and stores them encrypted
• Click Install the App and choose the account or organization that owns your repositories

Already created an App manually? Expand Already created an App? Connect it manually and paste its App ID, private key (.pem) and webhook secret. DeployKit verifies the credentials against GitHub before saving. The App's webhook URL must point at this instance and it needs the permissions listed below.

Installations and Repository Access

The GitHub App page lists every account where the App is installed, whether it has access to all or selected repositories, and flags suspended installations. From there you can:

• Install on an account — install the App on another user or organization
• Configure — open GitHub to change which repositories the installation can see
• Test connection — verify the stored credentials still work
• Refresh installations — re-sync the installation list from GitHub
• Disconnect — remove the App from DeployKit (the App itself stays on GitHub)

Installing, uninstalling and changing repository selection on GitHub are picked up automatically through webhook events. Prefer granting selected repositories over all of them — it limits what the App's private key can reach.

Connecting an Application

When creating an application, or from General → Source on an existing one (Connect through the GitHub App instead), pick the account, repository and branch from the lists. A connected app shows a GitHub App badge and no access token field. Listing installations and repositories requires the operator role on the project.

Auto-Deploy

The App subscribes to push and pull_request. A push deploys every connected application whose repository and branch match; matching uses the installation plus GitHub's numeric repository id, never the URL. If the repository still has an old hand-made webhook, its duplicate delivery is ignored for connected apps, so a push never deploys twice — but you can safely delete that webhook. See Webhooks & CI/CD.

Commit Statuses

For connected applications, DeployKit publishes a GitHub commit status on the deployed commit — for webhook-triggered and manual deploys alike:

• pending — when the deploy is queued and while it builds
• success — when the new container is healthy
• failure — when any step fails

The status context is deploykit/<app name> and its link opens the application in your panel, so you can use it as a required check in branch protection. Preview deployments report under their parent's context, so branch protection sees one stable check per application. Statuses are best-effort: if GitHub is unreachable the deploy still succeeds. They are on by default; set commitStatusEnabled: false via the application.update API to turn them off for one app.

Preview Deployments and PR Comments

With preview deployments enabled on a connected application, each pull request gets its own environment and DeployKit keeps a single comment on the PR — "Deploying preview", then "Preview ready" with the URL (or "Preview failed") and a link to the deployment logs, and finally "Preview removed" when the PR is closed. Redeploys edit the same comment instead of posting new ones. Previews inherit the parent's App connection, so they store no credentials of their own.

Permissions

The App requests only what these features need:

It never asks for checks, workflows, administration or issues permissions.

Disconnecting and Uninstalling

• Disconnecting the App in DeployKit leaves connected applications without credentials until you reconnect or give them an access token — you are asked to confirm if any app uses it
• Uninstalling the App from an account on GitHub never deletes applications: they become disconnected and fall back to their access token, or fail with a clear error
• The App is never included in a configuration export — it is tied to this instance's webhook URL. On import, applications are re-linked to the local installation that can see their repository