Set up a GitHub App

A GitHub App gives Coolify access to one repository, selected repositories, or every repository in a personal account or organization.

Use a GitHub App when you want repository selection, automatic deployments, and pull-request events through one integration. Use a deploy key when you cannot install a GitHub App or need read-only access to one repository.

Choose an installation method

Automated installation uses GitHub's manifest flow to configure the required permissions, webhook, credentials, and callback. Use this method for GitHub.com.
Manual installation requires you to create the app, permissions, events, credentials, private key, and installation yourself. Use it for GitHub Enterprise or a custom permission setup.

Automated installation is recommended because it reduces the number of credentials and settings you must transfer manually.

Example values

The screenshots use these example values:

GitHub App name in Coolify: GitHub App Tutorial
GitHub App name on GitHub: coolify-github-app-tutorial
Webhook endpoint: https://coolboxy.shadowarcanist.internal

Replace them with your own name and public Coolify URL.

1. Create a GitHub App source in Coolify

Sources page in Coolify with the Add button

Open Sources from the Coolify sidebar.
Select New source > GitHub App.

Enter a name for the source.
Enter the GitHub organization name when the app belongs to an organization. Leave Organization empty for a personal account.
Under Use this App for, select Pull request previews if you need preview deployments. Select Continue.

For self-hosted GitHub Enterprise, expand Self-hosted / Enterprise GitHub and enter its HTML URL, API URL, Git user, and Git port.

System-wide access affects every team

On self-hosted Coolify, System wide makes the GitHub App available to every team on the instance. Leave it disabled when only the current team should use the app.

Coolify Cloud does not offer this setting because a source cannot be shared with other Cloud customers.

2. Choose automated installation

GitHub App installation choices and webhook endpoint settings in Coolify

Use the Automated installation section.

In Webhook endpoint, choose Use an instance endpoint and select an Instance endpoint. Choose Use a custom endpoint and enter Custom endpoint when GitHub must call a different public URL, such as a domain exposed through a tunnel.

Enter only the base URL, such as https://coolify.example.com. Do not append /webhooks.

GitHub must reach the webhook endpoint

Repository access can work while automatic and preview deployments fail if GitHub cannot reach this endpoint.

Preview Deployments permission and Register Now button

Set Preview deployment access to Read and update pull requests when Coolify should add deployment information to pull requests. This grants read-and-write access to pull requests.

Keep GitHub deployments at Create GitHub deployments when GitHub should show each deployment and its status. This grants read-and-write access to deployments. Read Show deployments on GitHub.

The mandatory permissions grant read access to repository contents, metadata, and email addresses.

Select Register with GitHub.

3. Register the app on GitHub

GitHub manifest page for naming and creating the GitHub App

Enter a unique GitHub App name.
Select Create GitHub App.

GitHub returns you to Coolify after creating the app. Coolify stores the generated App ID, client credentials, webhook secret, and private key.

4. Install repository access

Install Repositories on GitHub action in Coolify

Select Install repositories in the repository-access prompt shown after registration.

Choose All repositories or Only select repositories, then select Install.

Use selected repositories when the app does not need account-wide access.

After GitHub returns to Coolify, confirm that the source shows an installation and repository-management actions.

5. Create an application

Coolify project page with the New button

Open the required project and environment.
Select + New.

Private Repository with GitHub App resource type

Select Private Repository (with GitHub App).

6. Choose the deployment server

Self-hosted Coolify includes localhost

A self-hosted installation starts with a localhost server. Coolify selects it automatically when no other deployment server is available.

Server selection for a new GitHub application

Choose the server where the application should run.

7. Choose the GitHub App

GitHub App source selection for a new application

Select the GitHub App source you created.

8. Configure and deploy the application

Repository selection for a GitHub App application

Choose a repository and select Load Repository.

Branch and build configuration for a GitHub App application

Choose the branch, Build pack, base directory, internal port, and any required build settings. Read Build applications when you need help choosing a build method.

Select Continue, configure the application domain and variables, then deploy it.

Open Deployment Logs and confirm that Coolify clones the selected repository and commit.

Change repository access

Open Sources, select the GitHub App, open General, then select Repositories. Change the installation's repository access on GitHub and return to Coolify.

Refresh the repository list before creating another application. Removing repository access prevents new clones and webhook deployments for applications that use that repository.

Show deployments on GitHub

GitHub deployments require Coolify v4.7.0

GitHub deployments are available in Coolify v4.7.0 or above.

When the GitHub App has the Deployments: write repository permission, Coolify reports each deployment and preview deployment to GitHub Deployments. GitHub then shows what is deployed on the branch and the pull request.

The production environment has the name of the application. A preview uses the name of the application with (preview).
Each status links to the deployment log in Coolify. After a successful deployment, the status also links to the first domain of the application or the preview.
When a pull request closes, Coolify marks its preview deployments as inactive.

This needs a private GitHub App. The public GitHub source of public repositories cannot report deployments.

To add the permission to an existing GitHub App:

Open Sources, select the GitHub App, then open Permissions.
Select Update on GitHub, set Deployments to Read and write, and accept the permission update on GitHub.
Return to Coolify and select Refetch. The GitHub deployments section shows write for Deployments.

Team access

A member who has access only to some projects, environments, or resources cannot select a team GitHub App for a new application or as the new source of an application. This needs write access on the whole team, in the UI and through the API. An application keeps the source that it already uses.

Detect build files

Use Smart Scan in the creation form to detect Dockerfiles or Compose files and review optional environment-template imports. Set the correct Base directory before scanning a monorepo.

On this page