How we build from Git

Everything you need to know about our build system.

When a Koyeb Service is connected to a git repository, the build and deployment process will be performed each time a change is detected on your branch or if you manually trigger a redeploy action.

Koyeb uses Cloud Native Buildpacks to transform your application source code into an OCI image. We then deploy and run this image on the Koyeb platform.

In this documentation, we will explore the key information needed to understand how the build is performed.

Understanding the build process

Build steps

There are 6 steps during the build process:

  1. Clone: This is the first step of the build which clones your git repository
  2. Detect: The detector looks for an ordered group of buildpacks that will be used during the build phase.
  3. Analyze: Analyzes and restores files that buildpacks may use to optimize the build and export stages
  4. Restore: Restores layers from the cache if an existing OCI image has already been created for this repository
  5. Build: Transforms your application source code into runnable artifacts that can be packaged into a container
  6. Export: Creates the final OCI image of your application and pushes it to the Koyeb Container Registry

Once the export step is completed, the final OCI image is deployed in production and live traffic is routed to your service.

Build command

The easiest way to deploy is to rely on the default buildpack build commands which are automatically set depending on the application detected in your repository.

If the automated build steps are not enough to properly run your application, you can provide a custom build command. The custom build command is executed after the automated buildpack detection and build. This means that defining a custom build command will not override the automatic buildpack build steps and buildpack build commands will also be executed.

Keep in mind that, depending on the language you use, the buildpack might integrate cleaning steps before executing your build command. This might impact you if you rely on the result of the build performed by the buildpack.

Build logs

The Koyeb platform provides build logs for all deployments. Build logs are useful to understand what happened during the build stage and easily identify the root cause of build failures.

Each deployment has a unique build log, once a build is completed, no further logs will appear. Build logs are stored for 30 days.

Build locally

You can easily reproduce the different steps of the build using the pack CLI. This is useful to troubleshoot and for advanced use cases.

To install the pack CLI, you can read the official installation guide here.

Inside the repository, to build using pack, run:

pack build -B koyeb/builder YOUR_BUILDPACK_IMAGE_NAME

This command will perform a build of your application using the koyeb/builder builder and will generate an OCI image named with the name you passed to the pack CLI.

You can then run the container with your application:


For the complete Pack CLI references, please check out the Buildpacks documentation

To ensure maximal compatibility, we currently use a builder derived from the heroku/buildpacks:20 builder.

Execution, run command, and Procfile

There are two options to define the command used to launch your application:

  1. In the definition of your service with the run command field directly in the control panel.
  2. In your repository with a Procfile.

In some cases, a default run command might be set by the buildpack. Refer to the language-specific section to know more. If there is both a Procfile and a run command defined, the run command will take precedence over the Procfile.


A Procfile is a file you create at the root of your application repository to define how to launch your application.

Procfiles on Koyeb contain the command needed to run the app your production prefixed by web: like:

web: <command>

For instance to launch your application with yarn start:production, the Procfile will be:

web: yarn start:production

If no Procfile is present in your application repository, your application may fail to start properly and an error will appear in the logs printing the following:

failed to launch: determine start command: when there is no default process a command is required

Supported languages



Node.js applications are detected when the application contains a package.json file in the root directory of the repository.


Currently, supported versions of Node.js are 16.x, 18.x, and 19.x.

To specify the Node.js version to use, the engines section must be present to specify the Node.js version to use in your package.json.

{ ... "engines": { "node": "16.x" } ... }

If no version is specified in your package.json file, node 18.x will be used.

Important: If you set the NODE_ENV environment variable to production, modules listed in devDependencies of your package.json will be removed once the build step has completed successfully. To keep all modules listed in both dependencies and devDependencies at runtime when setting NODE_ENV to production, add the following environment to your Service configuration:

  • NPM_CONFIG_PRODUCTION=false if you use npm
  • YARN_PRODUCTION=false if you use yarn



Python applications are detected when the application contains a requirements.txt or file in the root directory of the repository.


Currently, supported versions of Python are python-3.11.2, python-3.10.10, python-3.9.16, and python-3.8.16,

To specify the Python version to use, add a runtime.txt file in the root directory of your repository with one of the versions mentioned above. For instance, to use Python 3.8, your runtime.txt file must contain all three version number components (major, minor, and patch):


If no version is specified, python-3.11.2 will be used.



Go applications are detected when the application contains at least one of the following:

  • A go.mod at the root of the project
  • A Godeps/Godeps.json file, identifying the application as being managed by godep
  • A vendor/vendor.json file, identifying the application as being managed by govendor
  • A src directory, which has subdirectories, contains one or more .go files, identifying the application as being managed by gb.


By default, the version used to build your application is fetched from your dependency manager metadata file. You can change the version by updating the appropriate metadata file or setting the $GOVERSION environment variable, depending on the dependency manager you use.



Ruby applications are detected when the application contains at least one of the following:

  • A Gemfile indicates a Ruby application
  • A indicates a Rack application
  • A config/environment.rb indicates a Rails 2 application
  • A config/application.rb containing the string Rails::Application indicates a Rails 3 application


By default, your application is built using the Ruby version defined in your Gemfile. If your Gemfile does not contain a ruby entry, your app will be built using Ruby (MRI) 3.1.2.



PHP applications are detected when the application contains a composer.json file in the root directory of your repository. Even if your application does not require Composer to run, the file must be there to indicate your app is a PHP application and contain the following content.



If no PHP version is specified on your composer.json file, your application will be built using the PHP 8 runtime. To specify a specific runtime, the following instruction must be present in your composer.json file:

{ ... "require": { "php": "^8.2" } ... }

Never use a specific version like 8.2.3, instead, use the ^ or ~ next significant release operators to ensure that you get appropriate updates upon push as they become available.



The default build system for Java applications when using heroku/buildpacks:20 builder is Maven. Java applications are detected when a pom.xml file is detected inside the root of your directory.


You can use a specific Java version by creating a file called in the root level of your application with the following content:


Accepted major version values are 1.8, 11, 13, 15, 17, and 19.

If you do not specify a Java version, the default value is set to 1.8