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:

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

In the Koyeb control panel (opens in a new tab), click the Create Web Service 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.

You can change the branch your project is deployed from in the Source section. You can also modify the autodeploy setting to choose whether to automatically redeploy your Service whenever changes are made to the tracked GitHub branch.

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.

You can further customize the build and run process using the fields below the builder selection. 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.
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, modify the Service type, regions, and Instance sizes for your Service as needed.

For additional configuration, you can set the environment variables your application needs, define the ports your service should listen on in the Exposed ports section, 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.

Examples

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 "github.com/koyeb/example-rails" \
               --git-branch "main" \
               --git-buildpack-run-command "rails server -b 0.0.0.0" \
               --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 "github.com/koyeb/example-flask" \
               --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 "github.com/koyeb/example-django" \
               --git-branch "main" \
               --git-builder "docker" \
               --ports "8000:http" \
               --routes "/:8000" \
               --env "PORT=8000" \
               --env "DJANGO_ALLOWED_HOSTS=.koyeb.app"

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.

Updating existing Services

You can modify a Service's configuration on the Service's Settings page.

After changing a Service's configuration, you must redeploy to apply the new settings. If your changes affect how the application is built, you must rebuild the application during this process.

You can choose between the following options depending on the scope of your changes.

Build and deploy

This option applies the updated configuration by rebuilding and redeploying the application. The new changes affect both the build and deployment stages.

Choose this option if your configuration may alter the build process.

Deploy without rebuild

This option redeploys your previous build with the new configuration.

Because it does not build the application again, this option is often faster. The trade-off is that the updated configuration only affects the runtime environment.

Choose this option if your changes do not impact the build process.

Pre-Built Docker Images Installation