To deploy your application, first navigate to the “Launch” tab, where you will see three types of applications to deploy: web, worker, or job. To understand the difference between these three application types, see the description of the types of applications. Then follow the four steps below to get your application linked up.

Selecting an Application and Build Method

Step 1: Selecting an application

After selecting an application type and clicking “Launch template,” you should see two options for launching your application: Git Repository and Docker Registry. Select Git Repository. You should then be able to search for your connected repositories: if you are not seeing your desired repository, see the Adding/Updating the Porter Github App guide.

Step 2: Selecting a Branch

Once you click on a repository, you will be asked to select a branch for that repository. This branch is the source branch where you want your application to be deployed from on pushes to that branch. For example, if you are setting up a production cluster, you might want your applications to be deployed on pushes to the production branch. If your branches are protected using Github’s branch protection rules, see the working with protected branches section below.

Step 3: Selecting a Build Method

After you select a branch, you will see your repository contents listed. What you select in this case depends on if you already have a Dockerfile, or if you’d like for Porter to detect and build your application automatically using a buildpack.

  • Dockerfile

  • Buildpack

If you already have a Dockerfile, you should locate the Dockerfile in your repository and select it. Once you click on the Dockerfile, you will be asked if you’d like to set the Docker build context to a different directory.

Docker Build Context

The Docker build context is the current working directory of your Dockerfile — in other words, where your Dockerfile assumes your application should be built from. For example, if your application code and entrypoint exist in the root of your repository, but your Dockerfile exists under the path ./docker/Dockerfile, you should select the root of the repository as the Docker build context.

Once you have selected a Dockerfile and your Docker build context, clicking Continue will bring you your application’s runtime configuration section. See step 4 for details.

Step 4: Deploy your Application

The last step is to set the runtime configuration for your application, and deploy it to your Porter cluster! This configuration varies by application type — for example, for web applications you can set the port that the application should be listening on, whether to expose this application to external traffic on a custom domain, and override the start command. For a detailed explanation of these configuration options for each application type, see the following guides:

After clicking Deploy, you can navigate to your application, your deployment will use a placeholder Docker image until the Github Action that deploys your application has completed for the first time:


You can monitor the status of the generated GitHub Action by checking the Actions tab in your linked repository.

Working with Protected Branches

At the moment, it is recommended that you turn off the branch protection rule so that Porter can write the file to the repository, and then turn it back on immediately afterwards. Porter will have built-in support for working with protected branches in a future version.

Customizing Buildpacks

Porter has built-in support Heroku and Paketo builders. The Heroku builder can use either the Heroku-18 stack or the Heroku-20, while the Paketo builder uses the Paketo Full Builder to build your application. If your application fails to build using one builder, it is recommended that you attempt the other builders which may detect configuration parameters slightly differently.

If Porter detects the runtime for your application, it will always use the detected buildpack to build your application. If your application requires multiple buildpacks (for example, a rails app that uses npm to compile static assets), you can add multiple buildpacks to the configuration that will be attempted.

If your runtime isn’t supported in any of these builders, you can input the URL to an open-source buildpack hosted on a public Github repository.