When you have a crucial deployment to make, or need to narrow a release window, the last thing you want to spend valuable time on is picking apart why a deployment failed or rebuilding the package on the fly.

One way around this is to check ahead of time that your deployment package will successfully deploy.

The deployment can then be swiftly promoted on demand, safe in the knowledge that the tests have passed and you haven’t missed any crucial dependencies.

We call these validated packages, and they're a great way to reduce deployment failures and make that release day less stressful.

Creating a validated package with Gearset

Run a comparison (see how) with an org as the target metadata location.
Note: You can't create a validated package when deploying to a source control repository (e.g. GitHub, Bitbucket etc)
Select some components to deploy (see how).
Click Next, then Pre-deployment summary.
On the Summary of items to deploy page, click Validate deployment.

Gearset will begin a check-only deployment to your selected org - which means that we will validate your deployment package against the target org. Nothing will be deployed to your target org at this stage. If anything goes wrong - for example, the deployment fails, or Apex unit tests don’t pass (if these are configured to run) - we’ll show you exactly what happened so you can fix it.
For advanced users, you can also specify the level of Apex unit testing you would like to carry out using the arrows on the Validate deployment button.

You can lear more about this feature from our documentation on Setting Apex test levels.

Once the validation completes, you'll be shown the Validation succeeded screen (or Validation failed if it has failed).
At this point, the package will automatically be saved on the Validated packages page in our app - unless you decide to deploy the package by selecting Deploy now option.

Deploying a validated package with Gearset

Once the validation has succeeded, you have three deployment options:

Deploy the package immediately.
Schedule the package for automatic deployment.
Work with team members to review and deploy the package together.

Deploying a validated package from 'Validation succeeded' page

From the Validation succeeded page, click Deploy now to begin immediate deployment of the package.

If your org supports Salesforce quick deploy, and you ran tests when validating your package, Gearset will attempt to deploy your package without re-running tests. This can make the deployment much faster than the initial validation.

Note: When a package is deployed, it is removed from the Validated packages page and added to your Deployment history page.

You can read more about the deployment history page in our article on Metadata deployment history.

Scheduling automatic deployment of a validated package

Gearset can automatically deploy your successfully validated package at a specified date and time, and send you a notification when the deployment is complete.

This means you don't have to be there to press Deploy now if you have a scheduled maintenance window.

You can schedule automatic deployment from either the Validation succeeded page, or from the Validated packages page using the Schedule deployment button (see picture below).

Schedule deployment from 'Validation succeeded' page

Click Schedule deployment.
Set the Date for deployment.
Set the Time for deployment (in your local time zone, set in the Profile settings > Notifications page in our app).
Optionally, enter email address(es) and/or mobile (cell) phone number(s) to receive the deployment results.
You can also add Slack or Microsoft Teams integration URLs, or to tick a checkbox to integrate with Chatter.
Finally, click Save scheduled deployment.

The scheduled date will now be shown for the package on the Validated packages page.

To change the time for a scheduled deployment, click the Schedule button again.
To remove the scheduling, click the red cross icon: that appears next to the scheduled time when you hover over it (as on picture above).
Note: you need to be the validated package owner, or a Team Owner on your Gearset team to have an option to delete a validated package.

Working with team members on validated packages

Validated packages are shared with other members of your team in Gearset, and those created by team members will appear in the results alongside your own.

If you have set up the requisite org permissions and shared access, you can collaborate on validated packages, inspect packages created by others, and even deploy them.

See the the guide on teams and sharing for more information:
Sharing org credentials with team members

Note: You cannot delete validated packages that belong to other team members. Unless you are a Team Owner on your Gearset team.

Viewing and managing saved validated packages

All validations (succeeded and failed) will be saved in the Validated packages page.

Note: When a package is deployed, it is removed from the Validated packages page and added to your Deployment history. The Validated packages page lists key information about your saved packages:

Owner: who created the package in Gearset.
Friendly name: you can enter a custom name to make it easier to identify the deployment in the future. This name will be carried through to the deployment history, if entered.
Validation status: Succeeded or Failed.
Source username: the source metadata location.
Target username: the target metadata location.
Package created: when the package validation began.
Expires in: time before the package expires (see section below for more information).
Scheduled: if the package has been scheduled for automatic deployment, the time and date of the deployment will be shown here.
Actions: gives you options to either View summary (of what's to be deployed in the validated package), or to Deploy the package to the target.

A number of actions can be performed from the Actions column. The actions depends on the validation status.

For Succeeded validations:

View summary: inspect the package contents and any deployment notes.
Clone package...: run a comparison (with your choice of source and target) with the same filter as the validated package you’ve chosen, and automatically select the same items to deploy.
Schedule: set a date and time for automatic deployment of the package.
Deploy: deploy the package immediately.
View comparison (via this button): view the original comparison that this validation was created from.
Download package (via this button ): download the raw package XML.
View components (via this button ): view the Validation succeeded page.
Delete (via this button ): delete the validated package from your history - this can't be undone!

For Failed validations you'll get the same options as above (to clone package, view comparison, download package, or delete it). You'll also be able to:

View errors: view the Validation failed page, which lists the deployment errors.

Other options available on the 'Validated packages' page

Selecting this button: allows you to preview additional options, such as:
- To view comparison
- Download your deployment package
- View components (this brings you to validation successful or validation failed page), or
- To permanently delete your validated package from the history (Note: deletion cannot be undone)

Filtering and searching validation packages

You can search for items in your history using the search box above the table of results.

By default, the validation history will display validations carried out in the last 10 days. You can change this filter view by clicking on the drop-down arrow on the right of the date range box.

The results can be sorted by column by clicking on a column header - by default they are sorted by date, with the most recent at the top.

On below example, we're sorting validated packages chronologically by their Friendly name:

You can also filter the history by validation status. You can view all validations (default), or choose your preferred options (e.g. to narrow down only to Successful validations) and select Apply filter:

Package expiry

Packages are based on snapshots of your environments created at the comparison stage. This means any changes in your orgs that happen between package creation and deployment won't be accounted for, and could be overwritten when the package is deployed.

In addition, Salesforce currently enforces a 10 day window on the quick deploy feature. Deploying a package outside of the 10 day validity window will mean tests will have to be re-run on deployment.

To reduce the chance of orgs changing under your feet, and to make the most of the quick deploy feature, Gearset validated packages expire 10 days after creation. The Expires in column on the Validated packages page shows how long until a package expires.

We recommend you deploy any validated packages within the 10 day window. You can, however, schedule and deploy them outside of this window, but will be shown a warning before confirming the deployment.

The warning will be a message:
"The package will expire before this time. We recommend you schedule deployment to run before the package expires."

Rolling back a deployment made with Compare and deploy

Comparing managed package metadata with Gearset

Deploy package straight to target

How can I change the package XML before deploying?

Resolving validation errors - "Not available for deploy for this organization"