Working with metadata Zip Files is a foundational deployment skill. The four-step routine covers: build a package.xml manifest for the components you want to deploy, retrieve or generate the Zip File, deploy it to the target org through the Salesforce CLI, and troubleshoot any failures by inspecting the Zip and the error log. Modern tools (Salesforce DX, Copado, Gearset) hide most of the mechanics, but the underlying Zip File still drives every operation. Understanding the format helps when automation breaks or when custom deployments are required.
- Build the package.xml manifest
Write a package.xml file that lists every metadata component your deployment includes. Group components by type; under each type, list the specific members (named components) or use the wildcard (*) for everything. Set the API version to the target Salesforce release. For deployments derived from source control, generate the manifest dynamically from the Git diff so only changed components ship. Tools like Salesforce CLI sf project deploy start with --source-dir do this automatically; manual deployments need explicit manifests. Validate the manifest XML against the metadata schema before deploying.
- Generate the Zip File
From Salesforce DX source, run sf project convert source to mdapi to produce a metadata API format Zip File. Alternatively, retrieve from a source org with sf project retrieve start using your package.xml. The output is a directory containing the package.xml at the root and one subfolder per metadata type with the component files inside. Compress this directory into a Zip File for tools that need the wire format directly. Most modern tools work with the directory and Zip internally; manual workflows compress the directory by hand.
- Deploy the Zip File to the target org
From the Salesforce CLI, run sf project deploy start with --metadata-dir and --target-org parameters. The CLI uploads the Zip to the target org and starts the deploy job. Watch the deploy progress in the CLI or in Setup, Deployment Status. For validate-only deploys, add --dry-run. For Apex test execution, add --test-level RunLocalTests or --test-level RunSpecifiedTests --tests. Capture the deploy id from the CLI output; you can resume monitoring or cancel the deploy by id later. For deployment from a CI pipeline, parameterize the credentials and the target org alias.
- Troubleshoot failures by inspecting the Zip and the error log
On any deploy failure, the CLI returns an error log listing failed components and the reason for each. Open the package.xml and confirm the component is listed. Open the corresponding file in the Zip and inspect the metadata XML for obvious issues: API version mismatch, missing field references, profile XML conflicts. Common fixes: bump the API version, add missing dependencies to the package, regenerate the profile XML against the target org schema, fix the Apex test that dropped coverage below 75 percent. Re-deploy after each fix and confirm the failure is resolved before moving on.
- Missing files in the Zip but listed in package.xml cause deploy failure. Conversely, extra files not in package.xml are silently ignored. Always regenerate the manifest before packaging.
- Profile XML can be huge and notoriously hard to diff. Use Permission Sets for everything you can and use tools like Sfpowerkit to clean Profile XML on retrieve.
- Apex deploy requires 75 percent test coverage org-wide post-deploy. A deploy that drops coverage below the threshold fails entirely, even if the changed code itself is fully covered.
- Validate-only deploys do not write changes but still consume API quota and platform compute. Run them strategically; do not validate from CI on every single commit if quota is constrained.
- Metadata API format and Salesforce DX source format are different. Mixing them in the same directory produces deployment errors. The Salesforce CLI converts between them; do not try to mix manually.