Skip to main content
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

​
Options

​
Deployment Options

FlagShortDescription
--file-fPath to the porter.yaml configuration file (optional if app already exists)
--appOverride the app name specified in porter.yaml
--target-xSpecify a deployment target (name or ID)
--wait-wWait for the deployment to complete before exiting
--preview-pDeploy 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.
FlagDescription
--exactDisable config merging with existing app configuration

​
Build Options

FlagDescription
--no-buildSkip building a new image and deploy with an existing image
--no-pullDon’t pull the previous image before building
--tagSpecify a custom image tag (overrides value in porter.yaml)
--image-repositorySet the image repository to use
--build-contextOverride the build context directory
--build-methodSet build method: docker or pack
--dockerfileOverride the Dockerfile path (for docker builds)
--builderSet the builder to use (for pack builds)
--attach-buildpacksAttach buildpacks to use (for pack builds)
--verboseShow verbose output during build

​
Environment Options

You can pass environment variables and secrets directly via command-line flags without modifying your porter.yaml.
FlagDescription
--variablesSet environment variables as key=value pairs (overrides porter.yaml)
--secretsSet secrets as key=value pairs (overrides porter.yaml)

​
Validation Options

FlagDescription
--validateCheck that the porter.yaml file is valid YAML syntax
--dry-runPerform server-side validation to confirm the configuration is valid without applying changes

​
Advanced Options

FlagShortDescription
--helm-overrides-file-vPath to a file containing Helm value overrides
--attach-env-groupsComma-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.
VariableDescription
PORTER_TOKENAuthentication token (required for CI/CD)
PORTER_HOSTPorter API host URL
PORTER_PROJECTTarget project ID
PORTER_CLUSTERTarget cluster ID
PORTER_APP_NAMEApp name (alternative to --app)
PORTER_DEPLOYMENT_TARGET_IDDeployment target ID
PORTER_TAGImage tag to deploy

​
Examples

# 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/[email protected]

      - 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