| name | metadata-api-retrieve-deploy |
| description | Metadata API retrieve/deploy via sf CLI and package.xml: manifest authoring, destructiveChanges, deploy options (checkOnly, testLevel, rollbackOnError), CI scripting. NOT for DX source format conversions (use salesforce-dx-source-tracking). NOT for unlocked packages (use unlocked-packages). |
| category | devops |
| salesforce-version | Spring '25+ |
| well-architected-pillars | ["Operational Excellence","Security"] |
| tags | ["metadata-api","sf-cli","package-xml","deploy","destructive-changes"] |
| triggers | ["salesforce metadata api retrieve package.xml manifest","sf project deploy start checkonly testlevel","destructivechanges pre vs post for metadata removal","rollbackonerror false partial deploy risk","metadata api ci pipeline authentication","package.xml wildcards vs explicit members"] |
| inputs | ["Source org auth alias","Target org auth alias","Metadata scope (component types, names)","Deployment policy (check-only, test level)"] |
| outputs | ["package.xml manifest","destructiveChanges manifest (if removing)","sf CLI retrieve and deploy commands","CI pipeline stanza"] |
| dependencies | [] |
| version | 1.0.0 |
| author | Pranav Nagrecha |
| updated | 2026-04-21T00:00:00.000Z |
Metadata API Retrieve / Deploy
Activate when retrieving or deploying Salesforce metadata via sf CLI (Metadata API or Source Format). This skill covers manifest authoring (package.xml), destructive-change handling, deploy options (checkOnly, testLevel, rollbackOnError), and CI pipeline wiring. Missteps corrupt orgs: partial deploys with rollbackOnError=false leave production half-configured; wildcards in package.xml pull thousands of unrelated components.
Before Starting
- Decide manifest scope. Explicit members (safer for CI) vs wildcards (broad retrieve for initial capture).
- Choose test level. Production deploys require
RunLocalTests or RunSpecifiedTests.
- Decide rollback policy.
rollbackOnError=true is the safe default; false creates partial-state risk.
- Pre or post destructive? Pre runs deletions before adds (safe for rename); post runs deletions after (safe when new metadata depends on old).
Core Concepts
package.xml manifest
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>Account.Industry__c</members>
<members>Account.Region__c</members>
<name>CustomField</name>
</types>
<types>
<members>AccountTrigger</members>
ApexTrigger
60.0
