Running your first deployment

Synchronize your source and target metadata with a few clicks

Jason Mann avatar
Written by Jason Mann
Updated over a week ago

Deploying metadata changes between a source and target with Gearset can be done in a few clicks. To deploy changes, you must start from the comparison results between a source and target. To learn how to run a comparison, view this support article.

When you run a deployment, the metadata configuration you select from your source is applied to your target, bringing the two into sync for that metadata.

Select metadata items to deploy

The first stage to deploying some changes is selecting the metadata items you want to include in the deployment. 

To select an item, click the checkbox next to its name. Below, I've selected a new custom field I've created in my developer org:

To view all selected items at any point, navigate to the Selected items tab. To select all items in the table, click the checkbox on the left-hand side of the title row. You can combine results filtering and searching to narrow down the results in the table, and quickly select multiple items.

For more on exploring comparison results, see this article.

Identifying subcomponents and dependencies

Gearset can help you identify and include metadata dependencies using its unique dependency analysis. For supported metadata types, related items and dependencies will be listed in a tree view in the results grid. 

To view an item's dependencies, click the small black arrow next to the metadata item name. This will expand the item out into a tree view. There are several subsections of dependency:

  • Components: lists the constituent components of the parent item; in a custom object, for example, this would include its custom fields and list views.

  • Depends on: the parent item depends on metadata in this list; to deploy the parent item, you will also need to include these items in your deployment (if they have changed).

  • Profiles and permissions: displays related profile and permission items to the parent item; for example, the field-level security changes associated with creating a new custom field.

  • Used by: metadata in this category depends on the parent item. To deploy these items, you will need to have first deployed the parent item, or else included it in the same deployment as these dependent items.

By expanding out the Profiles and permissions section for the new custom field shown below, you can see the related profile changes. Selecting any of these changes will show the differences in the diff viewer below the table:

To include all the associated profile and permission changes in the deployment, I can simply click the checkbox next to the Profiles and permissions header.

Alternatively, if I don't want to deploy all of them at once, I can select the checkboxes of one or more individual field-level security items.

Note: Gearset automatically breaks down profiles into their constituent metadata components. This means you can deploy just small parts of a profile without bringing across the whole profile from your source. This granularity lets you have total control over what you deploy.

For example, if you wish to deploy a few field-level security changes with a new custom field, you can do so without deploying the rest of the affected profiles. (For more on deploying field-level security, see this support document. For a guide on deploying profile components, see this article.)

In another example, below I can see my new Account.DiscountPercentage custom field Depends on my new Account.DiscountRate field. The XML shows that Account.DiscountPercentage references Account.DiscountRate. This tells me I should include Account.DiscountRate if I want to deploy Account.DiscountPercentage:

Gearset's automatic problem analysis

Once you've selected some items you want to deploy, click NEXT to prepare the deployment package. 

Gearset will now check for any missing dependencies or other potential problems that could cause your deployment to fail. If it finds anything that may cause issues, it will suggest changes to fix them. These fixes are optional, but following the recommendations will make your package more likely to deploy successfully. (For an introduction to Gearset problem analyzers, see this support document.)

In the screenshot below, Gearset has spotted an issue. Continuing with the previous example, I selected Account.DiscountPercentage but forgot to select the Account.DiscountRate field it depends on. This missing dependency will likely cause the deployment to fail:

Gearset is suggesting that we add in the missing referenced item. When you see a problem analysis page like this, there are three options:

  • To accept this suggestion, tick the checkbox(es) selected and click NEXT

  • To go back and modify your metadata selection, click Back to comparison and change the selected metadata items.

  • To continue to the pre-deployment summary without accepting the suggested changes, leave the checkbox(es) unticked and click NEXT.

In this case, Gearset correctly reminded me that I had forgotten the referenced custom field, so I ticked the box to bring it into my deployment.

When I then click NEXT, I am taken to the pre-deployment summary.

Pre-deployment summary

The pre-deployment summary (Summary of items to deploy) shows you key information about what you're about to deploy to your target. This includes the metadata items and their difference type, as well as your source and target:

There are several actions that you can perform at this point:

  • Add Deployment notes: adding a text note helps identify why you ran the deployment (e.g. a sprint name, or a feature release). Any text entered here is carried through to the post-deployment reports that Gearset generates. You can make deployment notes required for your team in Gearset (as shown in the screenshot above).

  • Ticketing items updates: if you have a deployment teams license (or above) with a ticketing software connected to your Gearset account, you can attach tickets to your deployments, and update their statuses.

  • Download package: save the final package file to your computer — useful if you want to inspect the raw XML before you release the changes.

  • Export: save the pre-deployment summary to a CSV file.

  • DEPLOY NOW: deploy the selected changes to your target.

  • VALIDATE DEPLOYMENT: perform a check-only deployment, running any tests in your target and checking the validity of the components without actually applying them to your target.

  • Back to comparison: if you want to make some changes to the items in your deployment package, click this to return to the comparison results.

For advanced users, you can also specify the level of testing you would like to carry out using the arrows on the DEPLOY NOW and VALIDATE DEPLOYMENT buttons. If you just click the main buttons (not the arrows), the default tests will run. For more information on the different test levels, see our article on Apex test levels.

You can also schedule the deployment from this page, or after carrying out a validation.

Running the deployment

Clicking DEPLOY NOW will begin the deployment. Once this process begins, Gearset will upload the package to Salesforce and queue it up for release. Depending on the number of components you're deploying, the performance of your Salesforce org, and the number of tests to run, this process can take a while.

You can safely navigate away from this page and the deployment will continue to run. To view the status of any deployments that are in progress, head to the deployment history page:

When the deployment finishes, you'll see a summary of the key information. Gearset will email you a copy of the deployment report as a PDF. You can also download this report from the deployment page, or from your deployment history.

And that's it! You have deployed the selected changes from your source to your target.

Did this answer your question?