porter apply

Deploy applications using porter.yaml with the porter apply command, supporting container builds, image updates, and preview environments

This command is the recommended way to deploy applications in CI/CD pipelines and for version-controlled infrastructure.

porter apply is the primary command for deploying applications using configuration-as-code. It reads a porter.yaml file, builds a new container image, and deploys your application to the cluster.

By default, porter apply performs a full build and deploy cycle. Use --no-build to skip building and deploy with an existing image.

You can run porter apply without a porter.yaml file to deploy using the existing application configuration. This is useful for triggering a new build and deploy without changing any settings.

Usage

porter apply -f porter.yaml [flags]

Prerequisites

• You’ve logged in to the Porter CLI after running porter auth login
• You’re connected to the correct project by running porter config set-project
• You’re connected to the correct cluster by running porter config set-cluster

Options

Deployment Options

Flag	Short	Description
--file	-f	Path to the porter.yaml configuration file (optional if app already exists)
--app		Override the app name specified in porter.yaml
--target	-x	Specify a deployment target (name or ID)
--wait	-w	Wait for the deployment to complete before exiting
--preview	-p	Deploy to a preview environment based on current git branch

Use --exact with caution. When set, this flag disables config merging with existing app configuration—any settings not explicitly defined in your porter.yaml will be overwritten. Most users should avoid this flag unless they need to completely replace the application configuration.

Flag	Description
--exact	Disable config merging with existing app configuration

Build Options

Flag	Description
--no-build	Skip building a new image and deploy with an existing image
--no-pull	Don’t pull the previous image before building
--tag	Specify a custom image tag (overrides value in porter.yaml)
--image-repository	Set the image repository to use
--build-context	Override the build context directory
--build-method	Set build method: docker or pack
--dockerfile	Override the Dockerfile path (for docker builds)
--builder	Set the builder to use (for pack builds)
--attach-buildpacks	Attach buildpacks to use (for pack builds)
--verbose	Show verbose output during build

Environment Options

You can pass environment variables and secrets directly via command-line flags without modifying your porter.yaml.

Flag	Description
--variables	Set environment variables as key=value pairs (overrides porter.yaml)
--secrets	Set secrets as key=value pairs (overrides porter.yaml)

Validation Options

Flag	Description
--validate	Check that the porter.yaml file is valid YAML syntax
--dry-run	Perform server-side validation to confirm the configuration is valid without applying changes

When you pass --validate (or run porter apply validate), Porter validates the file based on its format:

• Single-app porter.yaml — validated as one application configuration.
• Multi-app/addon porter.yaml (top-level apps: and/or addons: arrays) — each app and addon block is split out and validated individually. The command fails on the first invalid app or addon and reports its index in the array.
• Legacy addon schemas — addon blocks that use the deprecated legacy schema are skipped with a yellow DEPRECATION WARNING. Validation still succeeds for the rest of the file, but support for the legacy schema will be removed in a future release. Update the addon to the current schema to keep it covered by validation.

Advanced Options

Flag	Short	Description
--helm-overrides-file	-v	Path to a file containing Helm value overrides
--attach-env-groups		Comma-separated list of environment groups to attach

Environment Variables

You can also configure porter apply using environment variables. These are automatically set in the GitHub workflow that Porter generates for your application.

Variable	Description
PORTER_TOKEN	Authentication token (required for CI/CD)
PORTER_HOST	Porter API host URL
PORTER_PROJECT	Target project ID
PORTER_CLUSTER	Target cluster ID
PORTER_APP_NAME	App name (alternative to --app)
PORTER_DEPLOYMENT_TARGET_ID	Deployment target ID
PORTER_TAG	Image tag to deploy

Examples

Basic Deployment

# Deploy using porter.yaml in the current directory
porter apply -f porter.yaml

Workflow

When you run porter apply, the following steps occur:

1. Parse Configuration

   Porter reads and validates your porter.yaml file (if provided)

2. Build Image

   Porter builds and pushes a new container image (unless --no-build is specified)

3. Deploy Services

   Porter deploys or updates all services defined in the configuration

4. Wait for Rollout (if --wait)

   If --wait is specified, Porter waits for all services to become healthy

Configuration File

The porter apply command expects a porter.yaml file. For detailed documentation on all available configuration options, see the porter.yaml Reference.

Minimal Example

version: v2
name: my-app

services:
  - name: web
    type: web
    run: npm start
    port: 3000
    cpuCores: 0.5
    ramMegabytes: 512

CI/CD Integration

Most users deploy with porter apply through GitHub Actions. Porter automatically generates a GitHub workflow for your application that handles authentication and deployment.

The workflow below is similar to what Porter automatically creates when you connect your GitHub repository. You can find it in your repository at .github/workflows/porter_<app-name>.yml.

GitHub Actions Workflow

name: Deploy to my-app

on:
  push:
    branches:
      - main

jobs:
  porter-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set Github tag
        id: vars
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

      - name: Setup porter
        uses: porter-dev/setup-porter@v0.1.0

      - name: Deploy stack
        run: porter apply
        timeout-minutes: 30
        env:
          PORTER_CLUSTER: "1"
          PORTER_HOST: https://dashboard.porter.run
          PORTER_PROJECT: "1"
          PORTER_TOKEN: ${{ secrets.PORTER_TOKEN }}
          PORTER_TAG: ${{ steps.vars.outputs.sha_short }}
          PORTER_APP_NAME: my-app
          PORTER_DEPLOYMENT_TARGET_ID: your-deployment-target-id

Related Commands

• porter app update - Update an app without building
• porter app yaml - Export the current app configuration as YAML