When comparing two application connections and deploying configuration elements between them, some fields may have inherently different values. For example, a webhook URL in a staging app connection may be different than the same webhook's URL in the production app connection.
Tulip allows users to set environment variables for these fields, in order to specify what should be the unique value for each app connection. This helps maintain the right value for existing elements in each app connection, as well as automatically replacing relevant values for elements deployed to a new app connection.
Environment Variables structure and behavior
Environment variables consist of:
Scope: which elements and fields should be replaced
The scope is written as a Tulip Selector over Tulip element IDs. You can use * wildcards to traverse over all instances, or over all members of an array.
For example, if you want to replace login URL values in all Okta Application settings, the selector should beokta.Application.instance.*.settings.app.loginUrlApply variable on all nested fields in the scope:
If disabled, Tulip will only replace values in fields directly matching the selector
if enabled, Tulip will replace values in all fields matching the selector or nested within it
App connection specific values: what is the expected value in each app connection. Values should be in the correct format, as explained here.
Coming Soon: environment variables will soon support replacing values which appear as substrings of configuration fields. For example, this will allow users to replace dev.acme.org to prod.acme.org, even if the domain is found within a wider URL such as https://dev.acme.org/some/webhook/address
When deploying new elements, Tulip will replace a value when deploying if:
The current value in the source app connection matches the one specified in the environment variable
There is a value set for the target app connection
When comparing elements between app connections, Tulip will hide differences that match a variable's source and destination app connection values, to help users focus on meaningful differences. In this case, the element will show the value in the destination app connection, with a useful popover to show all values:
Tulip will also alert when detecting a difference with a value defined only on one side (with no value set for the other side).
Creating an environment variable
There are 2 ways to set a new environment variable:
Directly from an element difference, shown in deployments' comparison view
From the Environment Variables screen, reachable from the user icon -> Org Settings -> Environment Variables
Only organization administrators can create, edit or delete environment variables. The environment variables will apply to all user deployments.
Creating a new variable from the comparison view
During a deployment's comparison phase, you can set a new environment variable by selecting a "create environment variable" option on a specific difference. Do this on values which are expected to be different, and should not be "aligned".
You can set the variable to apply on the specific instance you're looking at (e.g. a single Okta application, CrowdStrike sensor, Cloudflare rule), or on all instances from this type. You can also set a variable which will replace these values across other fields as well, in all elements of this type.
After you select this option, review the suggested app connection specific values. Tulip auto-populates these values from other app connections. You can always choose to customize the rule values, scope, or any other setting from this screen. You can also add a "default" value, by selecting the "Any Other App Connection" option - this will be the expected value for any app connection not explicitly defined otherwise.
After creating an environment variable, configuration differences which have a matching environment variable will not be displayed as a difference. The source and destination values should match the ones specified in the environment variables.
If all differences in an element have matching environment variables, or have been excluded, the entire element row will not be shown in the comparison. Users can always toggle "Show Omitted Elements" to see these.
Creating a new variable from the Environment Variables view
Users can create a new environment variable directly from the Environment Variables view, accessible from user settings -> Org Settings -> Environment Variables:
When you create a new environment variable from this screen, you'll have to manually fill in the scope and app connection specific values. For the scope, it is recommended that you copy an element's Tulip ID to get a valid scope, and then adapt it to your needs.
App connection specific value types
When setting app connection specific values, make sure their type matches the expected value in the elements themselves. Auto-populated values will be formatted correctly.
Type of value | Expected format | Example values |
Boolean |
|
|
Integer | An integer |
|
String | A string surrounded by quotation marks |
|
Reference | A Tulip Element ID |
|
If you're not sure about a field's type, go to a configuration element which contains it and view its NACL to determine the expected type.
Environment Variables in deployment previews
When Tulip replaces a value to another value during a deployment, the replaced value will be marked in the deployment preview stage. You can see which environment variable caused the replacement.
If the replacement isn't correct, fix your environment variables from the Environment Variables screen, then regenerate the preview.
Environment Variables administration
You can always review all environment variables in their dedicated view, accessible from user settings -> Org Settings -> Environment Variables.
Here, you can edit variables, enable or disable them, or delete them if necessary.
You can also export the list of all environment variables, using the export button at the top right of the table.
Examples
Some common usages for environment variables include:
Okta admin email addresses: replace all fields which contain a specific admin email address, to another email address when deploying to production
Scope: okta.*.instance.*
Make sure to enable "Apply variable on all nested fields in this scope"