Deploying a destructive change through the Pipeline follows the same workflow and process as any other change. You commit the deletion to a feature branch, and if your CI job settings includes Deleted items (see below), you can promote the PR as normal through the Pipeline. After the PR is merged, the deletion will happen at the org level when the CI job is finished running.
A destructive change removes a component that does not exist in the source org, but does exist in the target. In a comparison, Gearset lists these under Deleted items. When they deploy, Gearset packages them in a destructiveChangesPost.xml file, so deletions run after the new and changed items in the same deployment.
By default, CI jobs deploy only new and changed items. Deletions in a pull request are skipped unless the CI job is set to deploy them.
Considerations before you start
Consider these points before you commit anything.
Data loss. Deleting a Custom field or Object deletes the data in it. Export any data you need before the change reaches an org that holds real data records.
References. Remove every reference to the component first: Apex, Triggers, Flows, Visualforce pages, Layouts, Reports, etc. A deletion that something still depends on will fail validation.
Metadata API limits. Some deletions can't be deployed at all, such as picklist values (they only become inactive) and custom label translations. Check Which destructive changes does the metadata API not handle? and plan manual steps for those.
CI job settings. Turning on Deploy deleted items means any item the CI job detects as deleted will be removed from that org, not only the one in your pull request. This is a team-wide decision, and you should consult your team before adjusting these settings.
Rename, not delete? If you're changing an API name, follow How to handle API rename of a Salesforce component through the Pipeline instead. A rename deploys as a new item plus a deletion of the old one.
Additional deletions possible in commit. If Gearset's repo cleaner is enabled, committing a destructive change to your branch will cause the cleaner to scan your branch for missing dependencies and remove them, meaning your PR could have additional, unrelated delations. See our documentation here for more information
Step by step
Make the deletion in your developer sandbox. Remove all references to the component, then delete the component itself in Setup.
Confirm deleted items is includes on every CI job. On the Pipelines page, open the settings for each environment's CI job, go to the Deployment behavior tab and check that
Deploy deleted itemsis checked. Do this for every environment up to and including Production, or the deletion will stop at the first job that skips it. If it's not included in your CI job filter, consult with your team before making any change, as this will impact all future PRs, not just yours.Create a feature branch from
main.Compare your Dev Sandbox to the feature branch. Use your Sandbox as the source and the feature branch as the target. The component you want to delete will appear under Deleted items, because it exists in the branch, but not in the Sandbox.
Select the deletion and any related changes. Tick the deleted item plus every changed item that removed a reference to it, such as updated Apex or layouts. Review problem analysis warnings before you continue.
Commit to the feature branch. Write a clear commit message that names what you're deleting and why. Gearset's repo dependency cleaner may add extra deletions for items left with missing dependencies; review them in the commit.
Open a pull request to the first environment. Gearset validates the PR against that org.
Merge once validation passes. The CI job deploys the new and changed items first, then runs the deletion at the end of the deployment.
Promote through the rest of the pipeline. Repeat the PR, validate, and merge cycle for each environment until the change reaches production.
Confirm the result. Check CI job history for each run.