Build & Deploy
Deploy with GitHub

Deploy with GitHub

The easiest way to deploy your applications on Koyeb is to connect the git repository containing your source code and let Koyeb manage the rest.

When using git-driven deployment, each time you push or merge your changes to your production branch, we build your application with all the required dependencies and deploy it to production. You benefit from built-in continuous deployment with a completely automated build and deployment process.

This document explains how to deploy an application from a GitHub repository to Koyeb.

Currently, we support deploying git repositories hosted on GitHub. On our public roadmap, you can show your interest in support for repositories hosted on GitLab (opens in a new tab) and Bitbucket (opens in a new tab).

Connect your GitHub account to Koyeb

To deploy git repositories from GitHub, you must first give Koyeb access to your GitHub account or organization. This process is only required the first time you deploy from GitHub and consists of:

  1. Installing the Koyeb app in the GitHub organization of your choice
  2. Granting Koyeb access to the repositories you want to deploy

In the Koyeb control panel (opens in a new tab), click the Create App button. Choose GitHub as your deployment method.

The prompt below will only be displayed if you do not already have GitHub configured.

On the page that follows, click the Install GitHub App button. You will be redirected to a screen on GitHub where you can select the account or organization you want to install the Koyeb app.

Next, grant access to all repositories or a selection of your choice and click the Install button to continue. You will be redirected back to the Koyeb control panel to continue your deployment configuration.

You can change the list of repositories Koyeb has access to by visiting the Installed GitHub Apps page (opens in a new tab) and clicking the Configure button associated with Koyeb.

Deploying from git with the control panel

Choose a repository

After choosing the GitHub deployment method, will need to select the repository you wish to deploy from. Your recently modified GitHub repositories will automatically populate the selection list and you can search for other repositories in your account.

Alternatively, you can also deploy repositories from any public GitHub repositories by pasting the full URL to the repository in the Public GitHub repository field and clicking the Continue button.

Some features are disabled when deploying from public GitHub repositories. For example, automatically deployment is disabled to give you more control over when your application is updated and what it is running.

Configure the Service

Once you select a repository, you will be taken to the Service configuration page.

First, choose a name for your Service and select the Branch of the repository you want to deploy.

Choose the builder

Next, choose the builder to use for your project:

  • buildpack (default): Uses buildpacks (opens in a new tab) to detect your project's language, install dependencies, and package the resulting executable environment into a runnable image.
  • Dockerfile: If your repository contains a Dockerfile, Koyeb can use it to build a runnable container image for your project.

To further customize the build and run process, expand the Build and deployment settings section. Here, depending on the builder you selected, you can optionally override the following fields:

  • Build command: Adds a custom build command to the build process that's executed after the automated build steps.
  • Run command: Defines the command to run to execute your application on deployment. This can also be defined in a Procfile in your repository. Read the Procfile section of the how we build from git page to learn more.
  • Work directory: The directory of the repository that contains your project's code. Read more on the monorepos page.
  • Autodeploy: Chooses whether to automatically redeploy your Service whenever changes are made to the tracked GitHub branch.
  • Privileged: Chooses whether the Service container is run in privileged mode (opens in a new tab). This advanced feature is useful when you need elevated system privileges like, for example, to start a Docker daemon within the container.

Final configuration

Next, choose the Service type, regions, and Instance sizes for your Service.

For additional configuration, click to expand the Advanced section. Here, you can set the environment variables your application needs, define the ports your service should listen on, customize health checks, and set your scaling configuration.

You can find out more about the available choices on the Services page.

Finally, select a name for the application you're deploying and click the Deploy button. Koyeb will clone your repository, build your project, and deploy it on the platform. You will be redirected to the Service's page where you can follow the progress of the build and deploy stages, view logs and metrics, and change your Service's settings.

Deploying from git with the CLI

If you prefer the command line, you can also deploy from GitHub repositories using the Koyeb CLI.

The basic command to create a Koyeb App and Service from a GitHub repository looks like this:

koyeb app init <APP_AND_SERVICE_NAME> \
               --git <GITHUB_REPOSITORY_URL> \
               --git-branch <GIT_BRANCH> \
               --git-builder <GIT_BUILDER> \
               . . .

Common options

There are many options available to define your configuration. The options below are relevant regardless of the builder you choose.

All of the options below that take an argument expect a string.
  • --git: The GitHub URL of the repository to deploy.
  • --git-branch: The git branch to use.
  • --git-builder: The builder to use to build the application.
  • --git-no-deploy-on-push: Disables automatic deployment when changes are made to the configured branch on GitHub.

Other options that aren't specific to the GitHub deployment method include:

  • --type: The Service type, either "WEB" or "WORKER" (default "WEB")
  • --instance-type: The instance type to deploy.
  • --regions: The regions to deploy to.
  • --env: An environment variable to set.
  • --max-scale: The maximum scale to use.
  • --min-scale: The minimum scale to use.
  • --ports: The ports to expose for "WEB" Services.
  • --routes: The paths to route for your "WEB" Service.
  • --privileged: Chooses whether the Service container is run in privileged mode (opens in a new tab). This advanced feature is useful when you need elevated system privileges like, for example, to start a Docker daemon within the container.

Builder-specific options

Most of the remaining options depend on the builder you choose for your project.

  • --git-buildpack-build-command: A custom build command to execute after the automated build steps.
  • --git-buildpack-run-command: A command to run to execute your application on deployment.
  • --git-workdir: The directory of the repository that contains your project's code. Read more on the monorepos page.


Here are some examples of how to use the Koyeb CLI to deploy applications from a GitHub repository.

To deploy a Ruby on Rails app (opens in a new tab) using the default buildpack builder, you could use a command like this:

koyeb app init "rails-example" \
               --git "" \
               --git-branch "main" \
               --git-buildpack-run-command "rails server -b" \
               --ports "5000:http" \
               --routes "/:5000" \
               --env "PORT=5000"

The above command uses the buildpack builder and defines a run command with the --git-buildpack-run-command flag. It also passes the ports, routes, and environment variables that the application expects.

A similar command can be used to deploy a Python app using Flask (opens in a new tab). This time, instead of giving a run command on the command line, we deploy from a repository that has a Procfile:

koyeb app init "flask-example" \
               --git "" \
               --git-branch "main" \
               --ports "5000:http" \
               --routes "/:5000" \
               --env "PORT=5000"

Lastly, this example uses a Dockerfile included in the repo to deploy a Django application (opens in a new tab):

koyeb app init "django-example" \
               --git "" \
               --git-branch "main" \
               --git-builder "docker" \
               --ports "8000:http" \
               --routes "/:8000" \
               --env "PORT=8000" \
               --env ""

Koyeb will clone the repository and build a Docker image using the included Dockerfile. It will then launch a container from the image using the settings you provided.