Ant Migration Tool
The Ant Migration Tool is a Java- and Ant-based command-line utility distributed by Salesforce for retrieving, deploying, and validating metadata between orgs over the Metadata API.
Definition
The Ant Migration Tool is a Java- and Ant-based command-line utility distributed by Salesforce for retrieving, deploying, and validating metadata between orgs over the Metadata API. Released in the late 2000s alongside the Metadata API itself, the tool wraps every API call as an Ant target so build scripts and CI/CD pipelines can deploy a package.xml manifest with a single command. For roughly a decade it was the canonical way to script Salesforce deployments outside the Setup UI, and it remains widely used in legacy pipelines that have not yet migrated to Salesforce CLI.
The Ant Migration Tool is feature-frozen. Salesforce no longer adds capability to it, and the modern recommendation for new pipelines is Salesforce CLI (sf or the older sfdx) plus Salesforce DX source format. The Ant Tool still works against current Metadata API versions, but the project layout it expects (a single package.xml plus mdapi-shaped directories) is one step behind the source-tracked, scratch-org-friendly workflow that Salesforce DX enables. Most large orgs still have Ant scripts in their build systems for at least one critical path; replacing them is one of the standard modernisation projects of the last few years.
How the Ant Migration Tool works and how it fits a modern stack
What the tool actually does
The tool ships as a single JAR file (ant-salesforce.jar) that registers Ant tasks like sf:retrieve, sf:deploy, sf:listMetadata, and sf:describeMetadata. Each task wraps an equivalent Metadata API call. Build scripts use those tasks inside an Ant target, pass a package.xml that describes what to retrieve or deploy, and run the build with ant deploy or ant retrieve. The tool authenticates with username, password, and a security token, or with OAuth via the JWT bearer flow added in later versions.
Package.xml, the manifest at the centre
Every Ant deployment is driven by a package.xml manifest. It declares Metadata API types (ApexClass, Flow, CustomObject, etc.) and the specific component names per type to include. The tool sends the manifest to Salesforce, which gathers the matching metadata, returns it as a ZIP, and unpacks it into the directory the script specified. Deployments work in reverse: the script zips a directory, the tool sends it to Salesforce, and Salesforce applies it as one transactional deploy with rollback on failure.
Validation, quick deploy, and test execution
Two flags shape every production Ant deploy. checkOnly=true validates without applying changes; this is the standard production pre-check that runs unit tests against the target org and reports failures without touching metadata. testLevel controls which Apex tests run: NoTestRun, RunSpecifiedTests, RunLocalTests, or RunAllTestsInOrg. Production deployments require at least RunLocalTests with 75 percent coverage and the test pass. Quick Deploy lets a previously validated deployment land without re-running tests.
Authentication options
Original versions used username, password, and security token in a build.properties file. Later versions added support for the JWT bearer flow, which uses a digital certificate to obtain a session without a stored password. JWT is the recommended path because it survives password rotations and avoids the security risk of storing credentials in plain text. Most production CI/CD pipelines now use JWT exclusively.
How it compares to Salesforce CLI
Salesforce CLI replaces the Ant tool with single binary commands: sf project deploy start, sf project retrieve start, sf apex run test, and so on. The CLI works against the same Metadata API plus the SObject Tree, REST, and Tooling APIs. It supports Salesforce DX source format (one file per component) which Ant does not. CI pipelines on the CLI tend to be shorter, faster, and easier to read. The CLI is the recommended choice for any new project.
Migrating Ant scripts to CLI
The migration is mostly mechanical: each ant target maps to one sf command. Authentication moves from build.properties to sf auth jwt grant. The metadata directory layout can move to source format with sf project convert. Test execution flags translate one to one. Most build pipelines that took a few days to write originally take a few hours to port; CI pipelines that ran for 12 minutes drop to 4 to 6 minutes after the move because the CLI parallelises better.
When the Ant tool is still the right answer
Three scenarios still favour Ant. The first is a long-running CI pipeline already integrated with Jenkins, Bamboo, or similar Ant-aware servers; rewriting works but rarely justifies itself if the pipeline is stable. The second is an org that uses mdapi format exclusively and has no plans to move to source format; both formats are supported, but the Ant tool is the natural fit for mdapi. The third is a Java- or JVM-centric build system that the CLI does not slot into cleanly.
Common gotchas
Three failures dominate Ant deployments. The first is missing component dependencies (a Flow that references a deleted Apex class), which the API surfaces as a deploy error but does not auto-resolve. The second is timeouts on large deploys; pollWaitMillis and maxPoll must be tuned for orgs with thousands of components. The third is test failure noise from unrelated changes; tightening testLevel to RunSpecifiedTests with a curated list is the common cure for flaky pipeline runs.
How to run an Ant Migration Tool deployment
Setting up the tool takes about an hour. The longer-term work is keeping the package.xml accurate as the org evolves and the test list current as classes are added.
- Install Java and Ant
Ensure a supported Java JDK is on the build machine and Apache Ant 1.10 or higher is installed. Verify with java -version and ant -version.
- Download ant-salesforce.jar
Get the latest jar from the Salesforce Tools download page and drop it into the build directory. Reference it in build.xml via a taskdef.
- Configure authentication
Set up build.properties with username, password, security token, and serverurl for legacy auth, or configure JWT bearer flow for the recommended path.
- Write a package.xml manifest
List the Metadata API types and component names to deploy or retrieve. Use the API version supported by the target org.
- Run validate, then deploy
Run ant deployCodeCheckOnly first to validate without applying. Once it passes, run ant deployCode (or use Quick Deploy) to apply the changes.
- Username/password authentication breaks every time the password rotates. Use JWT bearer flow for any production pipeline.
- Deployments roll back as one transaction on any error. Validate with checkOnly=true before applying to production to avoid surprise rollbacks.
- Large orgs need pollWaitMillis and maxPoll tuned. The defaults time out on deploys with thousands of components.
- The tool is feature-frozen. New Metadata API capability lands in Salesforce CLI first; Ant catches up later, if at all.
Trust & references
Cross-checked against the following references.
- Ant Migration Tool GuideSalesforce Developer Docs
- Salesforce CLISalesforce Developers
Straight from the source - Salesforce's reference material on Ant Migration Tool.
- Metadata API Developer GuideSalesforce Developer Docs
Hands-on resources to go deeper on Ant Migration Tool.
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. When was the Ant Migration Tool retired?
Q2. What is the recommended replacement for the Ant Migration Tool?
Q3. What technology was the Ant Migration Tool built on?
Discussion
Loading discussion…