Environment Variables

Environment variables are composed of key-value pairs set externally from your source code. They can influence the behavior of the web application, providing a way to adjust its configuration without changing the codebase. Each value can be modified based on the specific Headless Platform environment.

Modifications to environment variables do not retroactively affect past builds. They are effective only for subsequent builds.

Managing environment variables

To add new variables either visit the Headless Platform Environment Details page and click the Go to variables link of the Variables card (first image) or select the left-hand submenu Variables item (second image).

On first entry to this page you will see an empty Environment Variables table in the non-edit mode. To add a row select the Add environment variable button.

Enter a key and value for each of your variable rows. To add further rows, while in edit mode, press Add Variable and input additional key-value pairs. Then click Save changes to confirm.

Upon saving the table your changes are persisted but not yet in use, so you will be prompted to redeploy the Environment with the latest variables. This is optional but if you redeploy you will be taken to the Environment Details page & a redeploy will commence.

After saving, your environment variables will be displayed in the table. To edit them again, just click the Add environment variable button. You’ll be asked whether to redeploy each time you save.

You can download your existing environment variables list when not in edit mode. This is done via the download icon, below the Add environment Variable button.

This presents you with a popup modal with 2 options for download format: CSV & .env.

To upload your downloaded environment file, simply click the bulk upload button. The file should be in .env format.

This presents you with a pop-up modal, offering options to upload files from your computer or via drag-and-drop.

To modify existing variables, click the edit icon located below the Add environment variable button. Once in edit mode, you can modify or delete individual rows. You will also see a quick Add variable button for adding new entries.

You can remove a variable by clicking on the trash icon while in edit mode.

Note

You will need to rebuild your application to apply any changes you make to the environment variables using this process.

Limitations

Reserved variables and namespaces

Our Headless Platform reserves some environment variables and prefixes. You cannot use these for your own variables:

• PORT
• WPE_ prefix
• HEADLESS_METADATA prefix

If you try to use these reserved keys, our Headless Platform will display a warning and won’t save the variable.

Allowed format of keys

Environment variables’ keys on our Headless Platform must match the following regex:

[a-zA-Z_]{1,}[a-zA-Z0-9_]*.

Special environment variables

The table below lists the environment variables for customizing operations:

Environment Variable	Description	Example
HEADLESS_NO_PURGE_CDN	Omit purging the CDN cache after deployments. Note: this may impact your site’s content freshness.	true

System environment variables

Our Headless Platform automatically generates a collection of environment variables to provide users with metadata about their environments. This includes variables such as the Build ID or a flag that signifies whether the environment in question is a preview or production environment. You can find the complete list of system environment variables in the table below:

Environment Variable	Description	Example
CI	Present during the build step.	true
HEADLESS_METADATA	Indicates that system environment variables are added to your deployments.	true
HEADLESS_METADATA_SOURCE	Source control provider	github
HEADLESS_METADATA_REPOSITORY	Git repository name and owner	some-user/repo-name
HEADLESS_METADATA_APP_NAME	Name of the Headless Platform application	my-app
HEADLESS_METADATA_ENV_NAME	Name of the Headless Platform environment	main-env
HEADLESS_METADATA_COMMIT_SHA	Commit identifier for the current build	4e6f58b
HEADLESS_METADATA_ENV_BRANCH	Git branch used for the current build	main
HEADLESS_METADATA_PREVIEW_ENV	Flag that indicates if the environment is a ‘preview’ type	true
HEADLESS_METADATA_ENV_ID	Unique identifier for the Headless Platform environment	026bbe63-8043-1c3e-00e5-d95c5a12aa32
HEADLESS_METADATA_BUILD_ID	Identifier for the latest build	5f42ce7c-b894-887d-1b9e-69d2429acbdd
HEADLESS_METADATA_CLEAN_BUILD	Indicates if the build is a ‘clean’ build	false