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, by default, 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.

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 Web Service button. Choose GitHub as your deployment method.

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.

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:

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.

• --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.

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.

Managing automatic redeployment

By default, Koyeb automatically redeploys Services created from repositories owned by your GitHub organization. Whenever changes are committed to the deployed branch (either by pushing or merging), Koyeb will pull the latest changes and redeploy the Service. If the deployment is successful, it becomes the active deployment, replacing the previous deployment.

If you wish to modify this behavior, you can either turn off automatic redeployments entirely or commit a .koyebignore file to your repository to configure which file changes trigger redeployment.

Enabling or disabling autodeploy

If you do not want to automatically redeploy your Service when changes occur, you can disable this feature on a per-repository basis.

During Service creation or from the Settings page of an existing Service, expand the Source section of the configuration. Inside, use the Autodeploy checkbox to enable or disable automatic redeployment. Deploy the Service to implement your chosen configuration.

Using .koyebignore to ignore changes to specified files

You can control which changes trigger a redeployment by including a .koyebignore file in the root directory of your project repository. The .koyebignore file respects the same syntax as .gitignore files (opens in a new tab) and is used to list files and file patterns that should not trigger new deployments.

Files matching the listed patterns will not trigger a redeployment if changed. Thus, if all of the files modified by a new commit are mentioned in the project's .koyebignore file, no new deployment will be triggered. This is especially useful for non-application files like README files, documentation, or example configurations that do not affect application behavior.

As an example, here is a .koyebignore file excluding some common non-application files and directories:

README.md
CONTRIBUTING.md
.env.example
docs/

If a commit only changes the listed files, no deployment will occur. If the commit includes any changes to files not listed in the .koyebignore file, a new deployment will be triggered and the entire repository will be copied, built, and deployed as usual.

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.

Save

If you want to save your changes, but do not wish to redeploy your Service at this time, use the Save option.

Saving a deployment records the current configuration without immediately deploying it. These saved configurations are called stashed deployments and are available in the Service's deploy history alongside conventional deployment. Once a configuration is saved, you can safely exit the Service Settings page and return to it later to continue modifying the settings or to deploy the stashed changes.

On the Service overview, you can view a list of all of the Service's deployments, including stashed deployments. From here, you can choose from the available deployments and click Redeploy to deploy the given configuration.

Deploy with build

The Deploy with build 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

The Deploy without rebuild 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.