Introducing Tags to Keep Your Salesforce Environments Organized

In all but the most trivial Salesforce DevOps pipelines, there can often be a significant number of active environments at any given time. For some of our customers, it’s not uncommon to have 30+ environments active in their OrgFlow stack at the same time.

Managing all those different environments can become challenging, particularly in automation and CI/CD contexts, because not all environments should be treated the same. Scripts or CI/CD jobs must sometimes treat different environments with different logic and processing.

One simple example might be to have a CI job that automatically any metadata changes pushed to an environment’s backing Git branch, but only for feature development environments —i.e. not for staging, UAT or production environments.

Hard-coding environment names

So how do you build a CI job that excludes the staging, UAT and production environments but runs for all others? Well, until now, hard-coding environment names has really been the only possibility.

But hard-coding is problematic, because environments come and go. In fact, as a best practice, you should strive to keep sandbox environments as short-lived as possible, lest they drift too far from your production org. OrgFlow is great at continuously keeping your sandbox environments up-to-date with your production org, but there are always things that OrgFlow doesn’t flow — most notably, users, roles and other things that are technically data rather than metadata.

Hard-coding environment names means that you have to constantly keep updating your scripts and CI/CD jobs whenever new environments are added to your stack, or old ones deleted. Aside from causing unnecessary churn in your script files, this is very tedious and error-prone.

It quickly becomes clear that we need a way to group and categorize environments that share certain common traits, so that we can base our scripts and CI/CD jobs on those traits instead of hard-coding environment names. But how? Sandbox names are limited to 11 characters, and must be unique. Descriptions are free text and lack any structure. Using either of them for grouping, categorization and programmatic decision making is a non-starter.

That’s where environment tags come in.

Enter environment tags

Tags add a way to group and categorize Salesforce environments that share certain common traits so that you can base your Salesforce DevOps script logic on those traits instead of hard-coding sandbox names.

Tags are a simple but powerful automation feature of OrgFlow, introduced in version 1.8.0. They allow you to develop scripts, CI/CD pipelines and other forms of automation that treat environments differently without having to hard-code environment names into your scripts. Instead, you can set different tags on different environments and base your script logic on those tags.

Anatomy of environment tags

Tags are arbitrary name/value pairs that you can set on the environments in your OrgFlow stack.

Environment tags are stored in OrgFlow’s cloud-based state store, and can therefore be managed and used from any device. Tags are pass-through and completely opaque to OrgFlow; OrgFlow ascribes no meaning to, and bases no processing on, the existence or values of any enviroment tags. Their meaning and use are completely up to you and the processes and pipelines you build around them.

A tag can either have a value (for example ownerEmail:dimitrius@acme.com) or no value (for example isDisabled). Tags with values are most useful when you need to filter or carry out actions based on values that may differ between environments, such as send an email to the owner of an environment. Tags without values are useful for modeling and acting on boolean conditions, such as excluding environments that have been temporarily disabled.

Both tag names and tag values are case-insensitive. Tag names may only contain alphanumeric characters, hyphens and underscores. Tag values may contain anything except newline characters.

Typical use cases

Thank to their flexibility, the potential use cases for environment tags are limited only by our engineering creativity, but here are some examples of the kinds of requirements we’ve come across while working with Salesforce DevOps customers:

• Categorize and group your environments and develop scripts or pipelines that apply particular logic or processing only for environments in a certain category or group. As an example, you might categorize all your environments as either dev, test, staging. In your CI/CD pipeline, you might only flow in changes in environments with the tag category:dev, because no changes made in test and staging environments should be preserved.
• Save arbitrary values on your environments and use those values as per-environment inputs to the logic or processing in your scripts or pipelines. As an example, you might designate a code owner for each development environment, and store the owner’s email address on each environment with the tags similar to ownerEmail:name@domain.com. In your CI/CD pipeline, you might then send an email to the owner of any environment where merge conflicts are detected.
• Flag your environments based on boolean semantics and use conditional logic or processing in your scripts or pipelines based on those flags. As an example, you might add a noMergeFromDownstream tag to some environments to allow environments to temporarily stop receiving automatic merges from downstream environments. In your scheduled upstream merge CI/CD pipeline, you would then exclude those environments from processing.

Using environment tags

To take advantage of environment tags, you need to be using OrgFlow version 1.8.0 or later.

To manage tags on your environments, use the new env:tags:set and env:tags:delete commands. Both commands allow you to set/delete multiple tags on multiple environments in a single command.

To see all tags on a given environment or to see a list of environments matching a given set of tags, use the env:list command.

To use tags in your scripts and CI/CD pipelines, use the env:list command. For simple filtering needs, you can use the --withTags argument of the env:list command itself to list environments matching a given set of tags and then use a loop in your script to perform some set of actions on those environments.

For more advanced filtering needs, you can use the --output=json argument to include all environment tags in JSON output, allowing you to base custom filtering and processing logic on those tags. You can also use a combination of both.

For a full end-to-end example using GitHub Actions, take a look at the Merge production into all sandboxes example workflow in our GitHub Actions demo template repository. You’ll notice that this workflow automates a scheduled upstream merge only to environments tagged with the upstreamMergeTarget tag.

That’s a quick introduction to the new environment tags feature in OrgFlow 1.8.0. We hope and think you will find this feature very useful when designing and building your Salesforce DevOps pipelines, and we can’t wait to see what you build with it. As usual, if you have any questions or feedback, don’t hesitate to get in touch—you’ll find all the ways to contact us on our website.