Why are we building this?
There’s an acute problem in the Agentforce and Data 360 deployment space (and therefore in the general Salesforce deployment space, as these are foundational products for the contemporary platform).
Deployments fail, not due to an issue with the metadata itself but because of the order in which that metadata needs to be deployed, activated, and then deployed again. We’re enhancing Gearset with the ability to take a complex set of changes which would otherwise fail deployment , and split them into a series of successful deployments and activations on the behalf of the user.
We’re starting with Agentforce and Data 360 metadata as our focus, as this is where we see the problem felt most acutely. We are also researching how we could expand this feature to generic metadata.
Why might some deployments need multi-step?
When you select metadata for deployment, the primary goal is to make sure that the work that has been described to you - maybe in a Jira, Azure or Asana ticket - can reach the target in its entirety. You're looking for missing dependencies, and adding them. If some of the components need activation, you're including the relevant post deployment steps.
However for some metadata types this can create an issue, especially with components that depend on those that require activation.
If a Prompt Template depends on a Retriever, then the Retriever must be present in the target org at the point that the Prompt Template is deployed. Traditionally, we might have just added the Retriever to the deployment package but that isn't possible. That's because the Retriever is a Data 360 component, and Data 360 is moved via Data Kits. Data Kits require activation (through a process called "data kit deploy) before their components are available.
This means that even though the Prompt Template and the Data Kit are deployed at the same time, at the point they both reach the target the Data Kit has not yet been activated and therefore the Retriever is unavailable. The deployment fails, despite all the correct metadata technically being included.
A multi step deployment in Gearset solves this, by understanding the requirement for certain metadata to be activated before it becomes available to its dependencies.
How can I use automatic multi-step deployments?
Select your metadata as normal. For example, you might choose an agent, the prompt template it uses, and the Data Kit that contains the retriever the prompt template depends on. You don’t need to do anything differently at this stage.
Review the message on the pre-deployment summary. A banner at the top of the screen explains that some components in your package must reach the target and be activated before the rest can deploy successfully. You can ignore this message and carry on with a single deployment, but it’s likely to fail for the reasons described in the banner.
Accept the split. If you choose to split, Gearset works out which components need to go first and moves them into the first deployment. Everything else is saved as a draft deployment for you to come back to.
Deploy the first part. Gearset deploys the Data Kit and activates it for you. Once activation finishes, the retriever is available in the target org.
Return to your draft deployments. Open the draft that holds the rest of your changes and refresh the comparison, so Gearset is working with the current state of the target org.
Deploy the second part. Problem analysis automatically updates the retriever ID in your prompt template to match the retriever now in the target org, so you don’t need to edit any XML. Then go ahead and deploy.
The result is that the whole piece of work reaches the target through Gearset, with no manual steps in the org.
Which scenarios are supported?
Multi step deployments currently support this scenario:
A prompt template that depends on a retriever inside a Data Kit. The Data Kit is deployed and activated first, then the prompt template (and anything that depends on it) is deployed.
We’re also researching other scenarios where a deployment fails because of order or activation rather than because of the metadata itself. These include, but are not limited to:
A prompt template linked to a flow that contains an Apex action. A known Salesforce issue means these can’t be deployed together in one package.
A bot version that depends on conversation message definitions. The conversation message definitions must exist in the target first.
Components that have to be deployed as inactive first. Examples are matching rules and stage assignments, which then need a follow-up deployment to restore their active state.
If any of these, or a scenario not listed here, is causing you problems, please tell us over the in-app chat.
Future development
We are continuing to release this work, as we actively gather user input and feedback.
Gearset doesn’t yet run the second deployment for you automatically. The second part is saved as a draft, and you deploy it yourself once the first part has completed.
In the future we will automatically trigger the second deployment after the first activation completes.
Multi step deployments aren’t yet available for Pipelines. They work for org-to-org deployments.
In the future you'll be able to manage multi-step deployments through pipelines.
The scenarios we're focused on at the moment are for Agentforce and Data 360, as we have found that deployments of these products often fail because of sequencing requirements.
We're collecting feedback at the moment to understand why splitting up deployments is necessary and to investigate how Gearset can automate that.