Coolify Docs

Appearance

GitHub App ​

Github app allows you to grant access to a single or mulitple private repositories from your either personal github account or your organization on github.

Why use github app with Coolify? ​

Scoped Access: The GitHub app lets you grant Coolify access to a specific repository, a selected group of repositories, or even all of your repositories. This gives you flexibility and better control over what Coolify can access.

When Not to Use github app with Coolify? ​

Lack of Permission: If you don't have the necessary permissions to install the GitHub app, or if you prefer not to install it, then it’s best not to use it with Coolify.

Installation Methods ​

There are two ways to install Github App on Coolify:

Example Data

The following data is used as an example in this guide. Please replace it with your actual data when following the steps:

  • GitHub App Name on Coolify: Github App Tutorial
  • GitHub App Name on Github: coolify-github-app-tutorial
  • Webhook Endpoint: https://coolboxy.shadowarcanist.internal

Automated Installation ​

1. Create a Github App on Coolify ​

  1. In your Coolify dashboard, click on Sources from the sidebar.
  2. Click the + Add button to create a new github app.
  1. Enter a Name for your App
  2. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue

INFO

  1. If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section.
  2. The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked.

WARNING

Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud

2. Set Webhook Endpoint ​

  1. Select the endpoint for github to send Webhook when a event (commit, pr) happens on github. If this endpoint is not reachable then automatic deployments won't work so if you decide to close port 8000 on your server you have to set the webhook endpoint as your Coolify dashboard domain
  1. Preview deployments are enabled by default and you can disable them if you dont want them
  2. Click on Register now button (this will take you to github)

3. Create Github App on Github ​

  1. Give your github app a name (this will be shown on your github app list and you can always change it later)
  2. Click on Create app button (this will take you back to your coolify dashboard)

4. Allow Github app access to repositories ​

  1. Click on "Install repositories on Github" button
  1. Select the repositories that you want this app to have access to (you can give access to all repositories or specific repositories)
  2. Click on "Install" button (this will take you back to your Coolify dashboard)

5. Create a New Resource on Coolify ​

  1. Select your project from the Coolify dashboard.
  2. Click the + New button to create a new resource.

6. Select Private Repository (with Github App) as Resource Type ​

Select Private Repository (with Github App) from the available resource types.

6. Choose Your Server ​

HEADS UP!

Coolify automatically selects the localhost server if you don't have any remote servers connected. In such cases, skip to the next step.

Choose the server where you want to deploy the application.

7. Choose Your Github App ​

Select the Github App you created in Coolify from the list of available Apps.

8. Configure the Application and Deploy ​

  1. Choose Repository and click on "Load Repository" button.
  1. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on builds for more details.)

Once configured, deploy your application.

That's it!

HEADS UP!

The Automated installation guide ends here. If you’ve followed the steps above, you can start using Github Apps now. The guide below is for those who want to manually install and set up Github App.

Manual Installation ​

1. Create a Github App on Coolify ​

  1. In your Coolify dashboard, click on Sources from the sidebar.
  2. Click the + Add button to create a new github app.
  1. Enter a Name for your App
  2. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue

INFO

  1. If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section.
  2. The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked.

WARNING

Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud

  1. Click on Continue button
  1. Save the Source ID of github app somewhere safe (source id is the UUID you see on your url bar after /github/)

We will need the following data to setup the github app:

  • App ID
  • Installation ID
  • Client ID
  • Client Secret
  • Webhook Secret
  • SSH Key

We will get these data in the next few steps.

2. Create a App on Github ​

Creating apps on github slightly varies for personal accounts and organizations so choose the correct one from the below section

  1. Go to your github account settings
  2. On the sidebar scroll down till you see "developer settings" and click on it
  1. Click the "New github app" button

3. Setup the Github App on Github ​

  1. Give your app a name
  2. Enter homepage url for your app (this can be anything)

  1. Scrol down till you see the "Post Installation" section

  2. Enter Setup URL: https://coolboxy.shadowarcanist.internal/webhooks/source/github/install?source=a8000cg0g0ogcc0ggkk8ow4k

  3. Enable the option Redirect on Update

  4. Enter Webhook URL: https://coolboxy.shadowarcanist.internal/source/github/events

INFO

You have to replace https://coolboxy.shadowarcanist.internal with your Coolify dashboard url and replace a8000cg0g0ogcc0ggkk8ow4k with the Source ID Step 1

  1. Enter Webhook Secret (this has to be a random string, you can use tools like Random String Generator)
  2. Enable the option Enable SSL verification
  1. Scrol down till you see the "Permissions" section
  2. Set Access to Read-only for Contents
  3. Set Access to Read and write for Pull Requests (Only needed if you plan to use Preview deployments feature)
  4. Set Access to Read-only for Email addresses

HEADS Up!

On the screenshot above for permissions section we have hidden lot of Permission and only shown the Permission needed to setup Github app for Coolify.

  1. Scrol down till you see the "Subscribe to events" section
  2. Enable the option Push
  3. Enable the option Pull requests (Only needed if you plan to use Preview deployments feature)
  4. Select the option Only on this account (Prevents others from installing our Github app to their github accounts)
  5. Click the button "Create Github App"
  1. Save the App ID and Client ID somewhere safe (we have to enter this on Coolify later)
  1. Click the Generate a new client secret button
  2. Save the client secret somewhere safe (we have to enter this on Coolify later)
  1. Scrol down till you see the "Private keys" section
  2. Click the Generate a private key button (this will automatically download the private key as a .pem file)
  1. Click "Install App" from the sidebar
  2. Click the "Install" button
  1. Select the repositories you want the app to have access to.
  2. Click the "Install" button
  1. Click the Settings icon (this will take you to your account or organization applications page)
  1. Save the Installation ID somewhere safe (Installation ID is the number you see on your url bar after /installations/)

4. Add Private keys on Coolify ​

  1. In your Coolify dashboard, click on Keys & Tokens from the sidebar.
  2. Click on Private keys tab.
  3. Click the + Add button to add a new private key.
  1. Give your Private key a name
  2. Paste the content of the .pem file which github automatically downloaded to your machine when you setup the Github App on Github
  3. Click on "Continue" button
  1. In your Coolify dashboard, click on Sources from the sidebar and select your Github app from the list
  2. Enter the details (App ID, Installation ID etc..) you saved on previous steps
  3. On "Private key" select the key you just added to Coolify
  4. Click on "Sync Name" button, if you see a success message then you have done everything correctly and you can start using the Github app!

5. Create a New Resource on Coolify ​

  1. Select your project from the Coolify dashboard.
  2. Click the + New button to create a new resource.

6. Select Private Repository (with Github App) as Resource Type ​

Select Private Repository (with Github App) from the available resource types.

6. Choose Your Server ​

HEADS UP!

Coolify automatically selects the localhost server if you don't have any remote servers connected. In such cases, skip to the next step.

Choose the server where you want to deploy the application.

7. Choose Your Github App ​

Select the Github App you created in Coolify from the list of available Apps.

8. Configure the Application and Deploy ​

  1. Choose Repository and click on "Load Repository" button.
  1. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on builds for more details.)

Once configured, deploy your application.

That's it!