sf-deploy-cli

Summary

The sf-deploy-cli is a tool for release managers and developers to effectively deploy features, hotfixes, and full releases to all environments in your unique software development process including DEV, QA, UAT, Training and Production environments. The sf-deploy-cli is a package of command line scripts integrated with the Salesforce CLI and any git source control repository.

1. What it is
2. What it isn't
3. Feature List
4. System Dependencies
5. Installation & Setup
6. Authentication
7. Configuration
8. Build Release Package
9. Command Reference
10. CLI Prompts
11. Version
12. Glossary

What it is?

A lightweight, developer friendly, deployment tool that assists and automates metadata deployments between environments based on source control.

What it isn't?

A full suite CI/CD process.

Feature List

• Quickly deploy features to mulitple sandbox environments daily as features are checked-in into source control.
• Manage and deploy full releases to any environment.
• Autogenerate deployment packages using source control to identify metadata changes.
• Autogenerate .forceignore file configured for each environment.
• Automatic test validation

System Dependencies

• VSCode
• Salesforce SF CLI
• Git Repository + Source Driven Development
• Sandbox and Prod Connections via VSCode and Authorize an Org

Installation and Setup

1. Ensure that the long-term support (Active LTS) version of Node.js is installed on your computer. To install the LTS version, go to https://nodejs.org/en/download/. To check your version number, run:

node --version

2. Run this command to install the sf-deploy-cli executable.

npm install sf-deploy-cli --global

3. Run this command to initalize project configuration:

sfdeploy --init

4. Ensure IDE and project are connected to active Git repository.
5. Authorize all org environments via IDE or SFDX for all environments in deployment lifecycle. i.e. In VSCode, cmd+P and Authorize an Org for all sandboxes.
6. Configure ./sf-deploy settings.
7. Run this command initalize deployment and follow prompts:

sfdeploy

Authentication

• All authentication is inherited from Git and Salesforce environment connections via VSCode.
• Git Repository, Connect and authorize salesforce project to any Git source-control repository.
• Salesforce Environments, Connect and 'Authorize and Org' to any/all salesforce environments in development lifecycle. sf-deploy-cli will only need the username for reference stored in ./sf-deploy/environments.json.

Configuration

• ./sfdeploy/forceignore - Structured forceignore settings used during deployment to auto-generate .forceignore file.
• ./sfdeploy/packages - List of manually created or auto-generated metadata packages.
• ./sfdeploy/environments.json - JSON configuration file for all salesforce environments. Setup all environment configurations tailored to your specific environment development cycle.
  • Environment Name:
    • username: Salesforce username of the user authenticated in VSCode for environment.
    • enabled: Boolean if environment is enabled for selection during deployment.
• ./sfdeploy/settings.json
  • packagePath
    • relative path to release packages folder
    • default value is './sf-deploy/packages' in root of project
  • features
    • autoGenerateForceIgnore
      • enabled, boolean if auto generate prompt is enabled during deployment, auto-set to false if disabled
      • default, true
    • runTests
      • enabled, boolean if run tests prompt is enabled during deployment, auto-set to false if disabled
      • default, false
    • validateOnly
      • enabled, boolean if validateOnly prompt is enabled during deployment, auto-set to false if disabled
      • default, false

Build Release Package

Use to automatically build a release package.xml based on the metadata differences between a source + destination branch. Used for release management and bundling multiple feature merges and commits into a single package for deployment.

1. Run this command initalize deployment and follow prompts:

sfdeploy --build

2. Enter the name of the release branch (i.e. release-v1)
3. Enter the name of the destination branch (i.e. master)
4. Package.xml will automatically be created based on diffs in ./sf-deploy/packages/release folder.

Command Reference

• sfdeploy, execute deployment workflow
  • --init, initalize sf-deploy-cli project configuration files in project root
  • --build, automatically build an xml package comparing two branches (i.e. release vs. master)

CLI Prompts

• Select deployment method
  • Select package, Select predefined package in ./sf-deploy/packages folder.
  • Generate package, Automatically generate package in ./sf-deploy/packageTemp.xml based on Git merge or commit.
• Select a package, List of available packages in sf-deploy/packages
• Select type of change
  • Current User Commits, List of current user commits to current repository
  • All Commits, List of all user commits on current repository
  • All Feature Merges, List of all feature merges to current repository
• Select commit, List of all git commits/merges
• Select org, List of environments to deploy selected package
• Run tests?
  • no, Skip running apex tests.
  • yes, Execute apex tests after successful environment to each selected environment.
• Validate Only?
  • no, Deploy package to environments
  • yes, Only validate successful deployment but don't actually deploy code.
• Auto-generate .forceignore?
  • no, Do not auto-generate .forceignore from ./sf-deploy/forceignore configuration
  • yes, Automatically, temporarily generate .forceignore file for deployment only.
• Ready to deploy? - Last step to review and confirm deployment.

Version

• Update package version execute following command:

npm install sf-deploy-cli --global

Glossary

Source-Driven Development

Using Git version control as the source-of-truth for all development activity. Provides greater team collaboration thru code reviews, conflict resolution, audit history, quality control and ensures best practices are followed. Tracks all changes ensuring no features are missed during deployment or lost in sandbox. Provides a superior development environment as engineers can using Salesforce DX and CLI.

Salesforce DX

The Salesforce Developer Experience is a modern best practice to develop and manage apps in Salesforce powered primarily by source-driven development, the command line interface, scratch org development and VSCode integration. Allows all engineers to spin-up unlimited* scratch orgs to test and build new features. Prevents team from having to constantly refresh sandboxes or have engineers stepping on each other.

Salesforce CLI

Salesforce Command Line Interface is a command line interface that simplifies development and build automation for Salesforce development.