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 lefthand 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.
Once the first variable row(s) has been added and saved, with or without redeploy, you will see the variable(s) in the non-edit mode version of the table. To modify this table again simply select the Add environment variable button again . Each time you save you will have to choose whether to redeploy, as before.
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.
You can modify existing variables by entering edit mode, accessible through the edit icon of the table, below the Add environment variable button. When in edit mode each row can be deleted or modified & there is a quick Add variable button, which works as the previously-mentioned Add environment variable one.
You can remove a variable by clicking on the trash icon while in edit mode.
Limitations
Reserved variables and namespaces
Our Headless Platform reserves some environment variables and prefixes. You cannot use these for your own variables:
PORTWPE_prefixHEADLESS_METADATAprefix
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 |