Deploy from a GitHub repository

Connect a GitHub repository to Porter for automatic builds and deployments with framework detection, branch selection, and CI/CD triggers

Porter connects to your GitHub repositories to build and deploy your applications. When you connect a repository, Porter detects your app’s framework, identifies services, and configures sensible defaults.

This guide covers deploying applications from GitHub. If you’re deploying from a container registry instead, see Deploy from a Docker registry.

---

Quick deploy

Agent

Ask an agent connected to the Porter MCP server to create the application for you. It detects your build settings from the codebase and opens a pull request that you merge to deploy.

1. Check the prerequisites

   • Connect your agent to the Porter MCP server. curl -fsSL https://agents.porter.run | sh does this for you and installs Porter’s skills.
   • Install the Porter GitHub App on the repository you want to deploy. The MCP server cannot install the GitHub App for you.
2. Ask your agent to deploy

   Deploy this GitHub repository to Porter. Detect the build method and application settings from the codebase.
   

   The agent resolves your Porter project and cluster, then calls create_app with the repository source and build configuration. Porter creates the application with a placeholder image and opens a pull request containing a GitHub Actions workflow.

3. Merge the pull request

   Review and merge the pull request that the agent returns. Merging it triggers the workflow that builds your code and runs the first real deployment.

Dashboard

For most applications, Porter’s automatic detection handles the heavy lifting. Here’s how to get your application running:

Connect your repository

From the Porter dashboard, navigate to your project and click Create Application. Porter attempts to deploy from a GitHub repository by default.

If this is your first time deploying from GitHub, install the Porter GitHub App. You can grant access to all repositories or select specific ones. Porter only needs read access to detect your code, and write access to set up automated deployments.

Once connected, select the repository containing your application code. Porter auto-selects the repository’s default branch (usually main or master) so you can start deploying immediately. If you need a different target for non‑production, use the Branch selector to switch to dev, staging, or any other branch.

Review detected applications

After you select a repository and branch, Porter scans your code. It identifies frameworks and languages, locates Dockerfiles, and determines the required services.

Within a few seconds, you’ll see a list of detected applications. Each card shows the app name (from your repo or directory), the detected framework or build method, and the path in your repository. If the detected build method isn’t right for your application, click the configure button (gear icon) on the card to change it.

For a simple repository with a single application, you’ll typically see one card. For monorepos containing multiple services, Porter detects each application separately. For example, a Node.js API in /api, a React frontend in /web, and a Python worker in /jobs each appear as distinct applications you can configure independently.

Previously deployed apps in monorepos

When you deploy from a monorepo that already has some services running on your cluster, Porter automatically identifies which detected applications are already deployed and hides them from the main list. This keeps the view focused on new applications you haven’t deployed yet.

A banner at the top summarizes what was detected. For example, if Porter finds 5 applications but 3 are already deployed, the banner indicates that 2 new applications were configured and 3 are already deployed.

To view the already-deployed applications, expand the Show N previously deployed app(s) section below the application list. Each previously deployed app card shows its name, build path, and the name of the existing deployment it matches.

If you want to re-create an already-deployed application (for example, to deploy a second instance with different configuration), click Add on its card. A confirmation dialog appears letting you know the build context is already deployed, and you can click Create anyway to add it to your new application list.

Porter matches detected applications to existing deployments using the build path and build method. If you change the build path of an existing application, Porter may not recognize it as already deployed.

If Porter didn’t detect an application you expected, or if you want to add another manually, click Add Application. To edit a detected application, click the configure button (gear icon) on the card to make updates.

Deploy

Once applications are detected, you can review each app’s start command and port, and open each app’s configuration page to see other pre‑configured values. When ready, deploy using the “Deploy X applications” button.

Porter creates a GitHub Actions workflow in your repository that handles building and deploying your application on every push to your selected branch. Your first deployment starts as soon as you merge Porter’s GitHub Actions pull request.

That’s it for a basic deployment. Porter has configured your application with production-ready defaults: appropriate resource allocation, a web service listening on the detected port, and automatic builds on every commit.

The sections below cover customizing these defaults when you need more control.

CLI

Deploy the application from a porter.yaml file:

porter apply -f porter.yaml

Learn how to define and deploy an application in the configuration-as-code guide.

---

Customizing your deployment

Porter’s defaults work well for many applications, but you have full control over every aspect of your deployment. The following sections explain each configuration area in detail.

Build configuration

Porter needs to know how to turn your source code into a runnable container. There are two approaches: Docker (via Dockerfiles) and buildpacks.

Docker builds

If your repository contains a Dockerfile, Porter can use it to build your application. This gives you complete control over the build process and is the right choice when you have custom system dependencies, need a specific base image, or have an application that buildpacks don’t support.

When you select Docker as your build method, you’ll need to specify the path to your Dockerfile relative to the repository root. If your Dockerfile is at the root level, this is simply Dockerfile. For monorepos, it might be ./api/Dockerfile or ./frontend/Dockerfile.

Buildpacks

Buildpacks automatically detect your application’s language and dependencies, then build an optimized container image without requiring you to write a Dockerfile. Porter supports buildpacks for Node.js (including Next.js), Python (Flask, FastAPI, Django), Ruby (Rails), and Go.

When Porter detects a supported framework, it selects the appropriate buildpack automatically. You’ll see the detected framework displayed on the application card. If the detection isn’t quite right, you can override it by selecting a different framework from the dropdown in an application’s configuration page.

Buildpacks work well when your application follows standard conventions for its framework. They handle dependency installation, asset compilation, and runtime configuration automatically.

Build path

The build path determines which directory Porter uses as the root for your build. For most repositories, this is ./ (the repository root). In a monorepo, you’ll typically set this to the directory containing the specific application, like ./api or ./frontend.

The build path affects where Porter looks for your Dockerfile (if using Docker builds) and which files are available during the build process.

---

Configuring services

A Porter application consists of one or more services—web services for HTTP traffic, workers for background processing, and jobs for scheduled tasks. By default, Porter configures a single web service for detected applications.

For a complete guide to service types, resource allocation, networking, environment variables, health checks, and more, see Configuring application services.

---

What happens when you deploy

When you click Deploy, Porter initiates several processes:

First, Porter creates a GitHub Actions workflow file in your repository at .github/workflows/porter.yml. This workflow triggers on pushes to your selected branch, building your application and deploying it to Porter. You’ll see a pull request created with this workflow file, and merging this PR enables automated deployments.

The initial deployment builds your application image using the configured build method and starts your services with the specified configuration. You can monitor deployment progress from the application dashboard, which shows build logs, deployment status, and any errors that occur.

Once deployed, subsequent pushes to your branch trigger automatic rebuilds and deployments. Each deployment creates new container instances, runs health checks (if configured), and shifts traffic only after the new instances are ready.

From your application dashboard, you can view logs, monitor resource usage, check deployment history, and make configuration changes. Configuration changes from the dashboard trigger new deployments but do not rebuild your application; rebuilds only happen when triggered from GitHub.