Environment groups

Share environment variables and secrets across multiple applications using project-wide groups synced to AWS, GCP, or Azure secret managers

An environment group is a set of environment variables and secrets that can be shared across multiple applications. Environment groups are project-wide — they can be used across all clusters and cloud accounts within your project. For example, if all of your web services need a shared set of API keys and database credentials, you can create an environment group containing those values and sync it to each service.

Environment variables configured directly on an application always take precedence over values from an environment group. This override applies on a per-variable basis — if an app sets API_KEY=xyz and a synced environment group has API_KEY=abc, the app-level value (xyz) is used.

How Secrets Are Stored

Environment group secrets are automatically synced to the secret manager of every cloud account linked to your project that has a running cluster:

• AWS — AWS Secrets Manager
• GCP — GCP Secret Manager
• Azure — Azure Key Vault

No secret data is stored on Porter’s infrastructure. Secrets only exist in memory on Porter’s servers momentarily during creation and updates.

If you already manage your secrets in a third-party secret manager, you can sync them into Porter as a read-only environment group instead. See the Doppler and Infisical integrations.

Creating an Environment Group

You can create a new environment group from the Env Groups tab on the Porter dashboard. Click New Env Group, enter a name, and add your variables and secrets.

You can also create environment groups from the CLI:

Interactive

porter env create

Variables and Secrets

Environment groups support two types of values:

Type	Description	Visibility
Variables	Non-sensitive configuration values (max 25 KB per value)	Visible in the dashboard and CLI after creation
Secrets	Sensitive values such as API keys, passwords, and tokens (max 25 KB per value)	Hidden after creation; stored in your cloud provider’s secret manager

When creating or updating an environment group, use the lock icon in the dashboard (or the -s flag in the CLI) to mark a value as a secret.

Files

Environment groups can also contain files for sensitive data such as certificates or configuration files. Files are managed through the Porter dashboard and are injected into your application’s container at the path:

/etc/secrets/<env-group-name>

Syncing Environment Groups to Applications

Environment groups can be synced to applications so that when the group is updated, all synced applications are automatically redeployed with the new values.

From the Dashboard

You can sync an environment group to an application during app creation or by navigating to the application’s Env Groups tab and adding the group. Click Update app to apply.

From porter.yaml

Add the envGroups field to your porter.yaml:

version: v2
name: my-app

envGroups:
  - production-secrets
  - shared-config

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

Environment groups listed in envGroups must already exist in the project before deploying.

Viewing Synced Applications

Open an environment group and select the Synced Apps tab to see every application currently consuming it, along with the clusters those applications run in.

Apps running in preview environments that reference the environment group are listed alongside regular applications and are tagged with a Preview badge so you can tell them apart from their base app (which often shares the same name). Selecting a preview card opens the app inside the preview environment it belongs to.

A cluster cannot be removed as a sync target while any application synced to the environment group — including preview environment apps — is still running on it. Tear down the preview environment (or remove the env group from its porter.yaml) before removing the cluster as a sync target.

Updating an Environment Group

When you update an environment group, all applications synced to it are automatically redeployed with the new values.

From the Dashboard

Navigate to the Env Groups tab, click the environment group you want to update, make your changes, and click Update.

From the CLI

Use porter env set to add or update variables, and porter env unset to remove them:

Set Variables

porter env set --group production-secrets -v LOG_LEVEL=debug -v FEATURE_FLAG=true

Pulling Environment Variables Locally

You can pull the contents of an environment group to your local machine for development:

Print to stdout

porter env pull --group production-secrets

The --variables (-v) and --secrets (-s) flags are mutually exclusive. If neither is specified, both variables and secrets are included in the output.

Listing Environment Groups

To see all environment groups in your project:

porter env list

This displays a table with each group’s name, current version, and last updated time.

Deleting an Environment Group

Environment groups can be deleted from the Settings tab on the environment group’s page in the dashboard.

You cannot delete an environment group that is synced to an application. Unsync the environment group from all applications before deleting it.

CLI Reference

For the full list of flags and options, see the porter env CLI reference.