Current limitations and requirements
You will need to have a Teams or Enterprise license to use this feature.
Gearset can do this 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 [email protected] might exist in a dev org, but it should be [email protected] 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, 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:
Choose your target org connection from the dropdown menu and click "Add Target". (Notice that two different users' connections to the same org are considered distinct org connections.)
A new section for the target org will appear, there you can click "Add environment variable"
Select the Metadata type "Profile" and Metadata item "Admin" from the respective dropdown menus. Note that you can only select a Field for specific metadata types like "Custom Metadata" and "Remote Site Settings". By default, the environment variable will be applied to the whole item.
Type in the value to find and the value to replace with, and click "Save". If the find value uses regex, ensure the "Regex" checkbox is ticked.
Each variable will display in a list below the environment variable addition options. These can be edited or deleted by clicking the kebab icon next to their entry. Note that you cannot create conflicting entries (i.e. variables that have the same target value to find in the same metadata type and item).
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 (manual and CI) that has the chosen target org connection*, even if the connection is a delegated connection, so 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 too.
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.
*Please note that two connection with different usernames that connect the same organization are treated as different org connections.
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, 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.
Using Regex
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:
Find what | Replace with |
|
|
|
|
|
|
But with regex, the same result can be achieved with a single environment variable:
Find what | Replace with |
|
|
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.
Want to know more about regex?
The Mozilla developer site has a great introduction to regex rules to get you started. You can visit it here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions