How to manage multiple environments using Porter YAML files

Last updated: September 19, 2025

When managing multiple environments (e.g., development, staging, production) for your application in Porter, you can use separate Porter YAML files for each environment. This approach allows you to maintain infrastructure as code and easily manage different configurations for each environment.

Creating environment-specific Porter YAML files

  1. Create separate YAML files for each environment in your repository. For example:

    • porter.dev.yaml for development

    • porter.staging.yaml for staging

    • porter.prod.yaml for production

  2. Place these files in a dedicated folder in your repository (e.g., .porter/). Avoid placing them in the .github/workflows/ directory, as this is reserved for GitHub-specific objects.

Note: You are not restricted to using porter.yaml as the filename. You can use any custom name for your Porter YAML files, such as the examples above or other naming conventions that suit your project structure.

Updating GitHub workflow files

To use the environment-specific Porter YAML files, you need to update your GitHub workflow files:

  1. Locate the workflow file for each environment in the .github/workflows/ directory.

In the "Deploy stack" step, modify the run command to specify the appropriate Porter YAML file using the -f flag followed by the path to your custom-named file. For example:

run: exec porter apply -f ./.porter/porter.dev.yaml

Example workflow file

Here's an example of how your updated workflow file might look:

name: Deploy to <app>
jobs:
  porter-deploy:
    runs-on: ubuntu-latest
    steps:
      # ... other steps ...
      - name: Deploy stack
        timeout-minutes: 30
        run: exec porter apply -f ./.porter/porter.dev.yaml
        env:
          # ... environment variables ...

Verifying the configuration

To ensure that your Porter YAML file is being used correctly:

  1. Check the "Deploy stack" step in your GitHub Actions workflow. You should see a message like: Using Porter YAML at path: ./.porter/porter.dev.yaml

  2. If the fields in the Porter UI are still editable after deployment, double-check the following:

    • Ensure the file path in the workflow is correct

    • Verify that the Porter YAML file exists in the specified location in your repository

    • Check the contents of your Porter YAML file to make sure it includes all the necessary configurations

If you continue to experience issues, contact Porter support for further assistance.