Gearset can apply environment variables for all metadata types, including custom metadata types, Lightning Web Components and Aura components.

Using environment variables allows people with information in their metadata that's specific to one org to keep it that way during a deployment.

For example the email address foo-dev@gearset-example.com might exist in a Dev org, but it should be foo-production@gearset-example.com in a Production org. Or, you might want different IP address ranges in your metadata, depending on whether the metadata is in a Dev or Production org.

Previously, this would need to be a manual change after the deployment, but environment variables allow the user to define where they want changes to be made, what value to find, and what to replace it with. This feature applies to both manual deployments and Continuous Integration deployments (CI jobs), and for deployments to orgs or source control. The value to find can be provided as plain text, or as a regex (regular expression).

To configure environment variables, go to the My Account section, then find Environment variables on the left-hand side.

There will be a dropdown to select the target org, along with tables of existing environment variables you have access to.

A concrete example of this could be replacing the Login IP Ranges in the Admin Profile Metadata.

If the dev admin IP range was 100.100.100.0 to 100.100.100.100 and the prod admin IP range was 200.200.200.0 to 200.200.200.100, then an environment variable could be created with the Prod org as a target.

You must be the owner of an org connection to add or edit an environment variable with that connection as the target.

We would set this up by doing the following:

You can also choose "Any item" instead of an item name to perform the replacement on all instances of the chosen metadata type.

Please note that you cannot modify XML tags within metadata using this feature, only the properties encompassed by the tags. For example, you cannot find and replace <value>SomeStringHere</value>. Instead, you would have to find SomeStringHere without the surrounding tags.

Once your environment variables are configured, they will automatically be used in any deployment (e.g. in manual deployments made via Compare and deploy and CI jobs) that has the chosen target org connection*, even if the connection is a delegated connection, as long as the metadata item they are configured for is selected as part of the deployment.

Environment variables will also be used during the validation of these deployment packages.

For instance, in the example above, the Admin Profile would need to be selected as part of the deployment package in order for the environment variable replacing the login IP ranges to take effect.

While only the owner of the target environment can create or edit environment variables on that environment, any user in the team who either owns or has delegated access to the connection to the target org can use its environment variables.

For manual deployments made via Compare and deploy, the environment variables that will be applied to a deployment can be viewed in the Problem Analysis and ENVIRONMENT VARIABLES screen, as shown below:

You can check the result of the replacement by downloading the deployment .zip file at the deployment summary stage. Once you've confirmed the variables are being applied as intended, proceed as normal, and the replacements will be made during the deployment.

Regex is an effective find and replace tool, allowing for more powerful matching than simple text. It can be used to match different spellings or localizations of the same word (e.g. check and cheque), navigating around case sensitivity (e.g. iPhone and iphone), wildcard matching (e.g. matching any phone number), and much more.

One example of where it can be used in Gearset is for matching multiple different email addresses. Consider how this might be set up without regex:

But with regex, the same result can be achieved with a single environment variable:

The "find what" value states that we want to match text that contains exactly @domain, followed by a full stop \., then by com, and finally by any amount of additional characters .* (such as develop1).

The full stop is escaped with a backslash (\) because full stops in regex represent a wildcard for matching any character, but in this case the intention was to match only on a full stop. The full stop at the end of the expression (.*) is not escaped, and is instead succeeded by an asterisk, which translates to match any character, any number of times.

The Mozilla developer site has a great introduction to regex rules to get you started. You can read more in their article on regular expressions.

You can also read Gearset documentation on:

The below table will show the outcome based on each method:

When you have a lot of variables to set up, or wish to setup a number of different environments, it can be useful to take advantage of some of the bulk setup tools available to you: clone and import CSV.

The clone option will allow you to clone all environment variables from one environment to another. Either add a new environment target via Add environment option, or find an existing environment target, and then click the button to Clone from....This will open a modal for you to select the source environment you want to clone environment variables from.

When you select a valid source and then click the Clone environment variables button, this will copy all environment variables from the source environment to the target environment.

Any environment variables present in the source that already exist in the target will cause the respective environment variable in the target to be updated to match the source. The rest of the environment variables will be created in the target.
​
This option is a helpful way to quickly replicate environment variables across multiple environments, allowing you to then edit the variables to the required values for the target environment.

A visual example would be this "uat1" org (source) from which we want to clone environment variables into the "prod1" org (target).

After selecting button we're selecting the correct "uat1" org from which the environment variables are going to be cloned from:

Then we select Clone environment variables button to confirm.

To export your environment variables in a CSV format, click on this icon: and select Export CSV.

The exported information would look as below.

The import CSV option is another way to quickly set up a number of environment variables in a target environment. This option allows you to setup your environment variables in a CSV file, which you can then upload for it to be validated, and then bulk import all the variables in the file to a target.

This option is found by hitting the three dot menu on an environment target and selecting "Import CSV".

This will open a modal with a button for you to select a CSV file to import. We have also provided you an option to download a template file that will provide you with the required field headings.
​
When you upload a CSV, the system will then validate the contents of that file, and display the environment variables it expects to upload. It will inform you if there are any errors understanding the CSV file, and it will inform you if any of the rows from your CSV file are not valid environment variables.

Simply hover over the cross in the displayed table to see the reasons why the environment variable is not valid.
​
The CSV must contain a header row with the exact titles of each field as in the table below (the template file provides these for you).

The table below gives an explanation for each field and what it must contain:

It is also possible to use the "Export CSV" on an existing environment target to download a file in the correct format for importing, make the changes you wish to make, and import to a different environment (or the same environment to update the variables).
​
This functionality is designed to enable you to quickly make bulk updates using Excel, Google Sheets, or other CSV handling software to manage the environment variable changes, and quickly allow you to setup, or edit, environment targets in the system.