Manifest File
A Manifest File in Salesforce is an XML file (typically named package.xml or destructiveChanges.xml) that lists the metadata components to retrieve from or deploy to a Salesforce org. The Salesforc…
Definition
A Manifest File in Salesforce is an XML file (typically named package.xml or destructiveChanges.xml) that lists the metadata components to retrieve from or deploy to a Salesforce org. The Salesforce Metadata API uses manifest files as the request specification: the file declares which metadata types and which named members within those types are part of the operation. The Salesforce CLI''s sf project retrieve and sf project deploy commands consume manifests to scope what metadata moves between local projects and Salesforce orgs.
Manifest files are the foundation of Salesforce metadata deployment outside source-tracking-enabled environments. Production org deployments, change sets, managed-package builds, and CI/CD pipelines all reference manifests to control exactly what metadata gets touched. The package.xml format dates from the early 2010s when the Metadata API was the primary deployment mechanism; modern source-tracking workflows handle simple cases without manifests, but every non-trivial deployment falls back to manifest-driven control eventually.
How Manifest Files drive Metadata API deployments
The package.xml structure
A package.xml manifest declares the API version, the metadata types, and the named members. The format is XML with a Package root element containing per-type types blocks. Each types block has a name (the metadata type, like ApexClass or CustomObject) and a list of members (specific component names or the wildcard *). The wildcard means all components of that type.
Wildcards vs. explicit members
Manifests support wildcards for retrieval (members tagged * pulls every component of that type) but require explicit member lists for some deployment scenarios. Production deployments typically use explicit lists for safety; sandboxes use wildcards more liberally for full-org refreshes.
destructiveChanges.xml for deletions
Manifest files come in pairs for many deployments: package.xml declares what to add or update; destructiveChanges.xml declares what to delete. The two files are zipped together with the source folder and sent to Salesforce as the deployment payload. Salesforce processes adds, then updates, then deletions in the configured order.
Salesforce CLI and manifests
The Salesforce CLI uses manifests via the -x flag: sf project retrieve start -x manifest/package.xml retrieves all components listed in the manifest. The CLI can also generate manifests automatically from a source directory or from an org''s metadata. Modern source-tracking workflows often skip manifests for simple cases but fall back to them for complex deployments.
Change Sets as manifest alternatives
Change Sets are Salesforce''s declarative alternative to manifest files. Admins pick metadata components in the UI; Salesforce builds the deployment payload internally. Change Sets are slower to build than manifests but require no XML knowledge; most admin-led deployments use Change Sets while developer-led deployments use manifests.
Manifest version and API version
Each manifest declares an apiVersion (e.g., 60.0 for Spring 25). The version controls which metadata types are available and how Salesforce interprets the components. Match the version to the target org''s supported API version; mismatches cause deploy failures.
CI/CD integration
Modern CI/CD pipelines (Copado, AutoRabit, Gearset, GitHub Actions) generate manifests automatically from git diffs between branches. The pipeline runs the diff, builds a package.xml of changed components, and deploys via Salesforce CLI. This is the standard pattern for any production deployment pipeline.
Build and use a Manifest File
Manifest files can be hand-written, generated by the Salesforce CLI, or produced by CI/CD pipelines. Most modern workflows use the CLI to generate them.
- Generate the manifest from a source folder
Run sf project generate manifest --source-dir force-app/main/default. The CLI scans the source and produces a package.xml.
- Or hand-write the package.xml
Create the file with the required XML structure: <Package xmlns=...><types><name>ApexClass</name><members>MyClass</members></types><version>60.0</version></Package>.
- Retrieve metadata using the manifest
Run sf project retrieve start -x manifest/package.xml -o my-org. The CLI pulls every component listed in the manifest.
- Deploy using the manifest
Run sf project deploy start -x manifest/package.xml -o my-org. The CLI deploys the listed components.
- Add destructiveChanges.xml for deletions
Create destructiveChanges.xml alongside package.xml with the components to delete. The CLI includes both in the deployment.
- Integrate with CI/CD
Set up the pipeline (Copado, AutoRabit, GitHub Actions) to generate manifests from git diffs and run deployments automatically.
The Salesforce API version the manifest targets.
Per metadata type with name and member list.
For deletions in the same deployment.
The tool that consumes the manifest.
- apiVersion mismatches cause deploy failures. Match the manifest version to the target org''s supported API version.
- Wildcards behave differently for retrieve vs. deploy. Wildcards are fine for retrieval; production deploys usually require explicit member lists.
- destructiveChanges.xml deletions run after adds and updates. The order matters for some metadata dependencies.
- Some metadata types are not supported by Metadata API. Check the Metadata Coverage Report before assuming a type can be manifested.
Trust & references
Cross-checked against the following references.
- Metadata API File-Based WorkflowSalesforce Developers
- SFDX MetadataSalesforce Developers
Straight from the source - Salesforce's reference material on Manifest File.
- Destructive ChangesSalesforce Developers
Hands-on resources to go deeper on Manifest File.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Manifest File in Salesforce DX?
Q2. When are manifest files necessary?
Q3. What's the file format?
Discussion
Loading discussion…