How to Deploy Custom Metadata Types Without Breaking Subscribers

Short answer: Decide who owns each field before the first release, because that choice is hard to walk back. Make values customers will tune subscriber editable, keep values your code depends on upgradeable, treat picklist values and protected record names as permanent, and test every upgrade against an org that already holds customer edits.

What does "breaking subscribers" mean for custom metadata?

A custom metadata upgrade breaks a subscriber in one of three ways:

• It overwrites a value the customer tuned. Their configuration silently resets on upgrade.
• It fails to install or upload. The platform rejects a change, such as a removed picklist value.
• It removes something still in use. A record your code or their configuration relies on is deprecated or deleted.

All three trace back to packaging decisions made before the first release, not to the deployment command. So the safe path starts with the type definition.

Which field manageability setting should you choose?

Every field on a packaged custom metadata type carries one of three settings, as Salesforce's Trailhead unit on protecting custom metadata explains:

• Upgradeable (developer controlled): you can change the value through package upgrades. Subscribers cannot edit it.
• Subscriber editable: the subscriber can edit the value after install, and package upgrades don't override their changes.
• Locked: neither you nor the subscriber can edit it after release.

Rule of thumb: if a customer will ever want to tune the value, make it subscriber editable and accept that you can no longer correct it in their org. If the value encodes how your code behaves, keep it upgradeable. Reserve locked for values that must never move. Note that subscriber editable fields on protected records are locked after release, so plan protection and manageability together.

What is permanent once you release?

• Picklist values are append-only. Salesforce's custom metadata implementation guide says developers can add values to a packaged picklist field but cannot delete or deactivate them, and subscribers cannot change them at all. A picklist field with inactive values also blocks package upload until you delete or reactivate those values.
• Protected record names are fixed. Per the Metadata API reference, the developer name of a protected record can't be changed after release. Name records as if they were public API.
• Protection only loosens. A protected type can become public, but a public type can't be converted back to protected. Protected types can only be created in Developer Edition and scratch orgs.
• Only you add fields. Subscribers can't add custom fields to a managed custom metadata type, so plan the field set before you ship.

What happens to records you remove from a package?

In second-generation managed packages, removed custom metadata records are marked as deprecated if they are visible to the subscriber org and hard deleted otherwise, according to Salesforce's guide to removing metadata components from 2GP packages. Deprecated components remain until a subscriber admin deletes them, and the Setup Audit Trail logs what the upgrade removed. Two consequences:

• Don't assume a removed record is gone. A visible record can linger as deprecated in the subscriber org, so code should stop referencing it rather than rely on its absence.
• Never reuse a removed name. Salesforce documents an upgrade failing because a leftover deprecated component collided with a re-added component of the same name.

If you plan your package model from scratch, our guide to switching Salesforce DevOps tools without breaking your pipeline covers keeping package history intact through a tooling change.

How do you deploy a custom metadata upgrade safely?

1. Review the type, not just the records. Manageability, protection and picklist changes are the ones you can't undo, so flag them in the pull request.
2. Package defaults, not customer configuration. Ship the records you need to own. Leave customer-specific values to subscriber editable fields or to records subscribers create themselves.
3. Build an upgrade test org. Install the previous released version, edit subscriber editable values and create a few customer records, then install the new version on top.
4. Assert what survived. Subscriber edits should be intact, upgradeable values should be updated, and removed records should be deprecated and unreferenced.
5. Change records from Apex only through the Metadata API. Apex can't use DML on custom metadata records. It deploys them asynchronously with Metadata.Operations.enqueueDeployment and a Metadata.DeployCallback class, and Salesforce limits how many of these deployments can be queued at once.
6. Allow for caching. Custom metadata records are cached after the first read, and requests already in flight during an update don't see the new values. Post-install checks should not expect an instant change.

When two branches edit the same .md-meta.xml record, follow our guide to resolving Salesforce metadata merge conflicts without losing anyone's work.

Does this matter if you don't ship a managed package?

Yes, in a smaller way. Internal teams deploy custom metadata records between sandboxes and production too, and deploying a record from source overwrites the target's copy. If admins tune records directly in production, the next deploy from Git silently reverts them. Either make Git the only place those records change, or keep admin-owned records out of the deployment. Our guide to helping admins deploy without touching Git shows how to give them a tracked path instead of direct edits.

Where does Serpent fit?

Serpent is the Salesforce DevOps platform built by Tekunda. It deploys custom metadata through the same reviewed pipeline as the rest of your metadata, with AI code review and a human approval before production, so a manageability or picklist change gets a second pair of eyes before it ships. Compare Serpent plans, or browse more SF Guides on packaging and CI/CD.

FAQ

Will a package upgrade overwrite subscriber custom metadata values?

Only on upgradeable fields. Package upgrades never override values a subscriber changed in a subscriber editable field.

Can I delete a picklist value from a packaged custom metadata type?

No. After release you can add picklist values, but you can't delete or deactivate existing ones.

Can Apex update custom metadata records?

Yes, but not with DML. Use Metadata.Operations.enqueueDeployment, which deploys asynchronously and reports back through a callback class.

Who makes Serpent?

Tekunda builds Serpent, a Salesforce DevOps platform with CI/CD, AI code review and human-approved deployments.