porter apply

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 also pass environment variables and secrets directly via command-line flags (--variables, --secrets) without modifying your porter.yaml.

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

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

Required Flags

Flag	Short	Description
--file	-f	Path to the porter.yaml configuration file

Deployment Options

Flag	Short	Description
--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

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)
--remote	Build remotely using kpack in the cluster instead of locally (experimental)
--verbose	Show verbose output during build

Environment Options

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	Validate the porter.yaml file without deploying
--dry-run	Perform server-side validation without applying changes
--exact	Disable config merging with existing app configuration

Advanced Options

Flag	Short	Description
--predeploy		Run the predeploy job before deploying services
--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:

Variable	Description
PORTER_APP_NAME	Override the app name (alternative to --app)
PORTER_PROJECT	Target project ID
PORTER_CLUSTER	Target cluster ID
PORTER_TOKEN	Authentication token

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

2. Build Image

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

3. Run Predeploy (if enabled)

   If --predeploy is specified or predeploy is defined in porter.yaml, the predeploy job runs first

4. Deploy Services

   Porter deploys or updates all services defined in the configuration

5. 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

For CI/CD pipelines, use environment variables for authentication and the --wait flag to ensure deployments complete before the pipeline continues.

GitHub Actions Example

- name: Deploy to Porter
  env:
    PORTER_TOKEN: ${{ secrets.PORTER_TOKEN }}
    PORTER_PROJECT: ${{ secrets.PORTER_PROJECT }}
    PORTER_CLUSTER: ${{ secrets.PORTER_CLUSTER }}
  run: porter apply -f porter.yaml

GitLab CI Example

deploy:
  script:
    - porter apply -f porter.yaml
  variables:
    PORTER_TOKEN: $PORTER_TOKEN
    PORTER_PROJECT: $PORTER_PROJECT
    PORTER_CLUSTER: $PORTER_CLUSTER

Troubleshooting

If your deployment fails, check the following common issues:

• Ensure your porter.yaml is valid by running porter apply -f porter.yaml --validate
• Verify you’re authenticated with porter auth login
• Check that your project and cluster are correctly configured with porter config

Validation Errors

Run with --validate to check your configuration:

porter apply -f porter.yaml --validate

Dry Run

Use --dry-run for server-side validation without making changes:

porter apply -f porter.yaml --dry-run

Related Commands

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