SFDX Deploy Tool - Easily deploy metadata using sfdx cli

Introducing SFDX Deploy Tool, a user friendly salesforce deployment tool which can be used to deploy metadata from one salesforce org to another.

Installation

To use this tool, you must have SFDX CLI installed in your system. You can download Salesforce CLI from here. 

Once you've downloaded and installed SFDX CLI, the next step is to clone the SFDX-Deploy-Tool repository from github. You can also download it as a zip file by clicking here. You can also use the below command to clone the repository:-

git clone https://github.com/rahulmalhotra/SFDX-Deploy-Tool.git

Once you've extracted this tool. You'll see a config.txt file with the information as shown below

sourceOrg=CR1 // Sfdx cli alias of source org

destinationOrg=PB1 // Sfdx cli alias of destination org

package.xmlLocationToDeploy=metadata\package.xml // Package.xml path

folderLocationForFetchedZip=metadata // Folder to save zip file of code fetched from source org

waitTimeInMinutes=10 // Deployment wait time in minutes

testLevel=RunSpecifiedTests // Specify whether to run test cases or not

runTests=TemperatureConverterTest,LeadProcessorTest // Comma separated names of test classes

folderLocationToUndeploy=metadata\destructive // Location of folder containing destructiveChanges.xml and empty package.xml used in case of un-deploy metadata from destination org

Follow the below steps to configure config.txt :-

1. Replace CR1 by the alias of your source org in sfdx cli ( If you haven't connected your source org using sfdx cli in past, you can delete CR1 and leave this space empty )
   
   
2. Replace PB1 by the alias of your destination org in sfdx cli ( If you haven't connected your destination org using sfdx cli in past, you can delete PB1 and leave this space empty )
   
   
3. As you can see, the package.xmlLocationToDeploy is given the value metadata\package.xml i.e. the package.xml inside the metadata folder will be used to fetch and deploy data. Either you can update the package.xml inside the metadata folder with your own metadata or you can specify the path to your own package.xml in the config file.
   
   
4. You can also see that the folderLocationForFetchedZip is given the value metadata. This means that when you'll fetch the metadata from source org it'll create a zip file inside the metadata folder and this zip file will be used later to deploy the metadata to destination org. If you want to use a different folder, you can specify the full path to that folder in config file.
   
   
5. Now we have the waitTimeInMinutes which is specified as 10 minutes you can update it according to your choice.
   
   
6. SFDX CLI provides you 4 test levels namely:- NoTestRun, RunSpecifiedTests, RunLocalTests and RunAllTestsInOrg. I have given my testLevel parameter the value of RunSpecifiedTests which will use the runTests parameter to get the test classes name which will be executed while deployment. You can also change it to NoTestRun or anything else from the available test levels but make sure that for the runTests parameter, you're specifying the testclass names separated by ",". The runTests parameter will be used only when the testLevel is set to RunSpecifiedTests.
   
   
7. The folderLocationToUndeploy should consists of the location of a folder which contains an empty package.xml file and a destructiveChanges.xml file. This will be used when you need to un-deploy or remove metadata from the org. The metadata specified in destructiveChanges.xml will be removed from destination org.

SFDX Deploy Tool is now ready for use.

Usage

You just need to make sure that the file sfdxdeploytool.bat and config.txt are in the same folder. If you're using the package.xml in the metadata folder and the destructiveChanges.xml which is present in the metadata/destructive folder, keep the folder structure as it is. After configuring, double click on sfdxdeploytool.bat and you're good to go.

In case, you've not specified alias for source or destination org, when you open sfdxdeploytool.bat you'll be asked to enter a new alias and also the instance url which is the login url for your org. In the login url, you can add the url according to the developer or sandbox edition or even a custom url.

Your default browser will be opened using which you can login into your org and authorize the sfdx cli to use your org. The config.txt file will be updated automatically as you authorize your org. Once you've your source and destination org properly setup along with the config.txt file, you'll see the below menu:-

1. Fetch metadata from source org

If you select the first option, it'll fetch the metadata according to the definition in package.xml whose path is given by:- package.xmlLocationToDeploy in config.txt. It'll create a zip file and store it in the folder specified by folderLocationForFetchedZip in config.txt.

In my case, the zip file is created in the metadata folder named unpackaged.zip as shown below:-

It'll consist of 4 apex classes which are specified in my package.xml and are present in my source org.

You can perform more operations by entering y once the operation is performed or can enter n to exit the tool.

2. Validating metadata in destination org

If you press option 2 in the main menu, the retrieved zip file will be validated in the destination org as shown below:-

In this case, no metadata will be deployed to the destination org, it'll only be validated. If you see the config file, I have specified the testLevel as RunSpecifiedTests and also specified two test classes in the runTests as:- TemperatureConverterTest,LeadProcessorTest. Therefore, my test classes are run during validation.

As you can see below, my code is validated successfully in the destination org and I have specified y at the end as I want to perform more operations.

I can search for deployment status in my destination org and view on the deployment status page that my metadata is validated successfully along with the test cases as shown below:- 

3. Deploying metadata in destination org

If you press option 3 in the main menu, the retrieved zip file will be deployed in the destination org as shown below:-

As you can see, all the test cases are run again and code is deployed in the destination org:-

While deploying, I can also go to the deployment status page of my destination org to see the deployment status as shown below:-

 

As you can see above, the deployment is successful in the destination org. Now the last option we have is to un-deploy metadata in the destination org.

4. Un-deploying metadata in destination org

In order to remove metadata from the destination org, I have specified the folderLocationToUndeploy in config.txt file. In my case, I am using the destructive folder present inside the metadata folder. The folder you'll specify for destructive deployment must consists of an empty package.xml and a destructiveChanges.xml file which will consists of the metadata definition we need to un-deploy.

Below is the package.xml present inside my destructive folder:-

And the destructiveChanges.xml which consists of 4 apex classes that I deployed to the destination org as I'll be removing the same.

When, I choose the 4th option from the main menu in my SFDX Deploy Tool, it'll automatically un-deploy the metadata mentioned in destructiveChanges.xml file as shown below:-

Similarly, if I check the deployment status in my org:-

It says deployment succeeded but, in actual the metadata is un-deployed or removed from the destination org. In case of un-deployment, no apex test classes are needed to run as we're doing destructive deployment.

So, that's all for this post. I hope you liked it and also liked the SFDX Deploy Tool. If you have any doubts, post them down in the comments and make sure to show your support by giving a star to the github repository here:- https://github.com/rahulmalhotra/SFDX-Deploy-Tool

You can also contribute to this repository, all the guidelines are mentioned in the CONTRIBUTING.md file and you can also tweet about this tool by using the twitter button in the README.md file at github.

Happy Trailblazing..!!