Salesforce Outbound Change Set: Building and Uploading Metadata

Session 82 covered the receiving side of the change set process — validating and deploying inbound change sets. Session 83 covers the sending side: how to build an outbound change set, select components correctly, manage dependencies, and upload to a target org.

Understanding both sides makes the full change set deployment workflow clear. This session completes the change set picture before the course moves to Salesforce CLI deployment in subsequent sessions.

What an outbound change set is

An outbound change set is a package of metadata components you create in a source org and upload to a connected target org. It is the mechanism through which changes move from one org to another without using the Salesforce CLI. You select the specific metadata you want to deploy, define the set, and upload it to the target org where it becomes available as an inbound change set for deployment.

Deployment connections

Before you can upload a change set from one org to another, a deployment connection must exist between them. To check or create deployment connections: Setup → Environments → Deploy → Deployment Connections.

This page shows all orgs in your deployment chain — typically your production org and all sandboxes associated with it. For each relationship, there are two directions: allow inbound (accept change sets from that org) and allow outbound (send change sets to that org). Click Allow to authorise each direction you need. In a typical development pipeline, you authorise: Developer Sandbox → Staging Sandbox and Staging Sandbox → Production. Both sides of the connection must enable the appropriate direction.

Creating an outbound change set

In the source org Setup, go to Environments → Change Sets → Outbound Change Sets. Click New. Fill in the name — use a descriptive naming convention that includes the date, the release or sprint identifier, and a brief description of what's included. The description field is visible to the receiving admin and should explain what the change set contains and why.

The change set detail page shows the component list (empty at first) and the Upload button (grayed out until you have at least one component). Click Add to start adding metadata components.

Adding components

The Add Components screen lets you filter by component type and search by name. Select Apex Class and search for the class you want to include. Select the checkbox and click Add to Change Set. Repeat for each component type you need to include.

You can add multiple components in a single session and across multiple component types. The component list accumulates as you add. To remove a component, click Remove next to it in the detail page.

The key principle: include all the components that have changed, not just the primary component you're deploying. If you modified an Apex class and updated the layout for the object it interacts with, include both. If you added a custom field and updated the validation rule that references it, include both.

View/Add Dependencies

After adding your primary components, click View/Add Dependencies on the change set detail page. Salesforce analyses the components you've included and surfaces a list of dependent metadata items — things the included components reference that also need to be present in the target org for the deployment to succeed.

Review this list carefully. Add the dependencies that aren't already in the target org. Dependencies that already exist in the target org don't need to be included — including them is harmless but adds unnecessary payload. The dependency checker doesn't catch everything, particularly: Apex code that references custom metadata types or custom settings (check these manually), reports in folders that don't exist in the target, and profiles that reference permission sets or apps not yet in the target org.

Uploading

When the component list is complete and dependencies are handled, click Upload. A dialog shows the available target orgs — the orgs that have an active deployment connection to your source org. Select the target org and confirm. Salesforce begins the upload process, which typically completes in seconds to a few minutes depending on the change set size.

Once uploaded, the change set appears in the target org's Inbound Change Sets list. The receiving admin is notified (by email, if notification is configured) and can proceed to validate and deploy it.

Managing the change set lifecycle

An outbound change set can be updated after creation but before upload. You can add or remove components freely. Once uploaded, the change set is read-only in the source org — you cannot modify what was sent. If you need to change something after upload, create a new change set (or a new version) and upload again. The target org will receive the updated version alongside the original.

After successful deployment in the target org, the change set remains in both orgs' histories for reference. There is no automatic cleanup — you can manually delete old change sets in the source org's Outbound Change Sets list once they are no longer needed for reference or audit purposes.

Common mistakes when building outbound change sets

• Missing profile changes: When you add a new custom object or field, the profiles that need to access it must also be included in the change set. Forgetting profiles is the most common reason a deployment succeeds but the feature isn't visible to users in the target org.
• Including too-broad profiles: The opposite problem — including a full System Administrator profile in a change set can overwrite permissions in the target org that were intentionally different. Include profiles with surgical precision, or use permission sets instead where possible.
• Omitting related automation: If a custom field has an associated flow, validation rule, or workflow that references it, include all of them. A partial deployment where the field exists but the automation doesn't can create unexpected behaviour.
• Naming conflicts: If a component in the change set has the same API name as something already in the target org but with different properties, the deployment will overwrite the target's version. Verify API names before uploading to avoid inadvertent overwrites.