Deployments
Deployment Best Practices. Focuses on CI/CD as this is the current best practice.
- Introduction - Why are we even doing it like this
- Chapter 1: The Why, When and By Whom
- Chapter 2: Software List
- Chapter 3: Basic Machine Setup
- Chapter 4 - Base Project Setup
Introduction - Why are we even doing it like this
Salesforce deployments are essential for managing and evolving Salesforce environments, especially in a consulting company setting. There are several methods for deploying metadata between organizations, including Change Sets, the Metadata API, and the Salesforce Command Line Interface (CLI). Each method has its unique advantages, but the introduction of Salesforce DX (SFDX) has revolutionized the process, making SFDX-based deployments the standard for the future.
The main reasons are because it is easy to deploy, and easy to revert to a prior version of anything you deploy as well - proper CI/CD depends on GIT being used, which ensures that everything you do can be rolled back in case of bugs.
Deployment Method | Advantages | Disadvantages |
---|---|---|
Change Sets |
- Easy to use with a graphical interface - No additional setup required |
- Limited to connected orgs - Manual and time-consuming - No version control - Can be done ad-hoc |
Metadata API |
- Supports complex deployments - Can be automated - Broad coverage |
- Requires programming knowledge - Steeper learning curve |
Salesforce CLI (SFDX) |
- Advanced automation - Supports modern DevOps practices - Version control |
- Steeper learning curve - Initial setup and configuration required - Requires trained staff to maintain |
Third-Party Tools |
- User-friendly interfaces - Advanced features and integrations |
- Additional costs - May have proprietary limitations |
Despite the complexity inherent in SFDX-based deployments, the benefits are substantial. They enable easy and frequent deployments, better testing by customers, smoother go-lives, and a general reduction in stress around project development and deployment cycles. The structured approach of SFDX ensures that deployments are reliable, repeatable, and less prone to errors.
To stay fact-based: SFDX deployments allow deploying multiple times a week in a few minutes per deployment. This allows very easy user testing, and also allows finding why a specific issue cropped up. You can check the Examples section to see how and why this is useful.
It is perfectly true that these deployments require more technical knowledge than third-party tools like Gearset or Changesets. It is our opinion that the tradeoff in productivity is worth the extra training and learning curve.
One thing that is often overlooked - you can NOT do proper CI/CD without plugging the deployment to your project management. This means the entire project management MUST be thought around the deployment logic.
This training is split into the following chapters:
-
Chapter 1: The Why, When and By Whom This chapter explores the fundamental considerations of Salesforce deployments within the context of consulting projects. It addresses:
- Why Deploy: The importance and benefits of deploying Salesforce metadata throughout the project lifecycle, from the build phase to UAT to GoLive.
- When: When in the project timeline should deployments be planned and executed to ensure smooth progress and mitigate risks. (Hint - it's often, but not in every org)
- By Whom: Roles and responsibilities involved in the deployment process, such as consultants committing changes, architects reviewing commits and system elements, and release managers overseeing and executing deployments.
Chapter 2: The What, How and How Frequently This chapter delves into the practical aspects of Salesforce deployments:
- What: Overview of the deployment tools used, including GIT, SFDX, SGD, Bitbucket, and your trusty Command Line.
- How: Detailed workflows and methodologies for using these tools effectively, tailored to specific roles within the project team (consultants, architects, release managers).
- How Frequently: Recommendations on the frequency of deployments throughout the project timeline to maintain agility, minimize conflicts, and ensure continuous integration and delivery.
Chapter 3: An Example Project and Deployment Flow This chapter provides a hands-on example to illustrate a typical project scenario and the corresponding deployment processes:
- Example Project: Overview of a hypothetical Salesforce consulting project, including its scope and objectives.
- Deployment Flow: Step-by-step walkthrough of the deployment lifecycle, from initial planning and setup through to execution and validation.
- Best Practices: Highlighting best practices and potential challenges encountered during the deployment process.
Chapter 4: Configurations, Templates and Setup This chapter focuses on the essential configurations and setup required to streamline the deployment process:
- Configurations: Detailed guidance on configuring Salesforce environments for efficient deployment management.
- Templates: Templates and reusable patterns for standardizing deployments and ensuring consistency across projects.
- Setup: Practical tips and strategies for setting up deployment pipelines, integrating with version control systems, and automating deployment tasks.
These chapters collectively provide a comprehensive guide to mastering Salesforce deployments within a consulting company, covering both strategic considerations and practical implementation details.
- Why Deploy: The importance and benefits of deploying Salesforce metadata throughout the project lifecycle, from the build phase to UAT to GoLive.
Chapter 1: The Why, When and By Whom
This chapter explores the fundamental considerations of Salesforce deployments within the context of consulting projects. It addresses:
- Why Deploy: The importance and benefits of deploying Salesforce metadata throughout the project lifecycle, from the build phase to UAT to GoLive.
- When: When in the project timeline should deployments be planned and executed to ensure smooth progress and mitigate risks. (Hint - it's often, but not in every org)
- By Whom: Roles and responsibilities involved in the deployment process, such as consultants committing changes, architects reviewing commits and system elements, and release managers overseeing and executing deployments.
Why do I Deploy ?
In traditional software development, deployments often occur to migrate changes between environments for testing or production releases. However, in the context of Continuous Integration (CI) and Salesforce development, deployments are just synchronization checkpoints for the application, irrelevant of the organization.
Said differently, in CI/CD Deployments are just a way to push commits to the environments that require them.
CI deployments are frequent, automated, and tied closely to the development cycle.
Deployments are never the focus in CI/CD, and what is important is instead the commits and the way that they tie into the project management - ideally into a ticket for each commit.
In software development, a commit is the action of saving changes to a version-controlled repository. It captures specific modifications to files, accompanied by a descriptive message. Commits are atomic, meaning changes are applied together as a single unit, ensuring version control, traceability of changes, and collaboration among team members.
Commits are part of using Git.
Git is a distributed version control system used to track changes in source code during software development. It is free and widely used, within Salesforce and elsewhere.
So if deployments are just here to sync commits...
Why do I commit ?
As soon as a commit is useful
Commits should pretty much be done "as soon as they are useful", which often means you have fulfilled one of the following conditions:
- you have finished working a ticket;
- you have finished configuring or coding a self-contained logic, business domain, or functional domain;
- you have finished correcting something that you want to be able to revert easily;
- you have finished a hotfix;
- you have finished a feature.
This will allow you to pull your changes from the org, commit your changes referencing the ticket number in the Commit Message, and then push to the repository.
This will allow others to work on the same repository without issues and to easily find and revert changes if required.
Take the Salesforce-built "Devops Center" for example.
They tie every commit to a Work Item and allow you to chose which elements from the metadata should be added to the commit. They then ask you to add a quick description and you're done.
This is the same logic we apply to tickets in the above description.
If you're wondering "why not just use DevOps Center", the answer is generally "you definitely should if you can, but you sometimes can't because it is proprietary and it has limitations you can't work around". Namely the fact that it only uses GitHub for now (2024-06-19).
To tie back to our introduction - this forces a division of work into Work Items, Tickets, or whatever other Agile-ism you use internally, and the project management level.
DevOps makes sense when you work iteratively, probably in sprints, and when the work to be delivered is well defined and packaged.
This is because....
When do I Deploy ?
Pretty much all the time, but not everywhere.
In Salesforce CI/CD, the two main points of complexity in your existing pipeline are going to be:
- The first integration of a commit into the pipeline
- The merging of multiple commits, especially if you have the unfortunate situation where multiple people work in the same org.
The reasons for this are similar but different.
In the case of the first integration of a commit into the pipeline, most of the time, things should be completely fine. The problem is one that everyone in the Salesforce space knows very well. The Metadata API sucks. And sadly, SFDX... also isn't perfect.
So sometimes, you might do everything right, but the MDAPI will throw some file or some setting that while valid in output, is invalid in input. Meaning Salesforce happily gives you something you can't deploy.
If this happens, you will get an error when you first try to integrate your commit to an org. This is why some pre-merge checks ensure that the commit you did can be deployed back to the org.
In the case of merging multiple commits, the reasons is also that the Metadata API sucks. It will answer the same calls with metadata that is not ordered the same way within the same file, which will lead Git to think there's tons-o-changes... Except not really. This is mostly fine as long as you don't have to merge your work with someone else's where they worked on the same piece of metadata - if so, there is a non-zero chance that the automated merging will fail.
In both cases, the answer is "ask your senior how to solve this if the pipeline errors out". In both cases also, the pipeline should be setup to cover these cases and error out gracefully.
"What does that have to do with when I deploy? Like didn't you get lost somewhere?"
The relation is simple - you should deploy pretty much ASAP to your remote repo, and merge frequently to the main work repository. You should also pull the remote work frequently to ensure you are in sync with others.
Deploying to remote will run the integration checks to ensure things can be merged, and merging will allow others to see your work. Pulling the other's work will ensure you don't overwrite stuff.
Deploying to QA or UAT should be something tied to the project management cycle and is not up to an individual contributor.
For example, you can deploy to QA every sprint end, and deploy to UAT once EPICs are flagged as ready for UAT (a manual step).
Who Deploys ?
Different people across the lifecycle of the project.
On project setup, the DevOps engineer that sets up the pipeline should deploy and setup.
For standard work, you should deploy to your own repo, and the automated system should merge to common if all's good.
For end of sprints, the automated pipeline should deploy to QA.
For UAT, the Architect assigned to the project should run the required pipelines.
In most cases, the runs should be automatic, and key points should be covered by technical people.
Chapter 2: Software List
This chapter explores the actual tools we are using in our example, the basic understanding needed for each tool, and an explanation of why we're doing things this way.
In short, our example relies on:
- Git
- A Git frontend if you are unused to Git - gitkraken is nice for Windows
- Bitbucket
- A good text editor (VSCode is fine, I prefer Sublime Text)
- The SF command line
- SFDMU, a SF command line extension
- SGD, a SF command line extension
- JIRA
You can completely use other tools if your project, your client, or your leadership want you do use other things.
The main reason we are using these in this example is that it relies on a tech stack that is very present with customers and widely used at a global level, while also leveraging reusable things as much as possible - technically speaking a lot of the configuration we do here is directly reusable in another pipeline provider, and the link to tickets is also something that can be integrated using another provider.
In short "use this, or something else if you know what you're doing".
So What are we using
The CLI
The first entrypoint into the pipeline is going to be the Salesforce Command Line.You can download it here.
If you want a graphical user interface, you should set up VSCode, which you can do by following this Trailhead. You can start using the CLI directly via the terminal if you already know what you're doing otherwise. If you're using VSCode, download Azul as well to avoid errors down the line.
We'll be using the Salesforce CLI to:
- login to organizations, and avoid that pesky MFA;
- pull changes from an organization once our config is done;
- rarely, push hotfixes to a UAT org.
For some roles, mainly architects and developers, we will also use it to:
- validate deploys to specific orgs in cases of hotfixes;
- setup SGD jobs in cases of commit-based deploys or destructive changes;
- setup SFDMU jobs for any data-based transfers.
What this actually does is allow you to interact with Salesforce. We will use it to get the configuration, security, and setting files that we will then deploy.
This allows us not only to deploy, but also to have a backup of the configuration, and an easy way to edit it via text edition software.
The configuration needed is literally just the installation to start - we'll set up a full project later down the line.
GIT
You'll then need to download Git, as well as a GUI if you're not used to using it directly from the command line. Git is VERY powerful but also quite annoying to learn fully, which is why we will keep its usage simple in our case.
We'll be using Git to:
- version our work so we can easily go back to earlier configurations in case of issues;
- document what we did when we modified something;
- get the work that other people have done;
- upload our work to the repositories for the project.
You'll need a bit more configuration once you're done installing - depending on the GUI you use (or if you're using the command line) the how depends on the exact software, but in short you'll need to configure git with your user name and your user email.
Logging in to Bitbucket and getting your repository from there will come later - once you've given your username and email, and configured your UI, we will consider that you are done for now.
If you're a normal user, this is all you'll see of git.
If you're a Dev or an Architect, you'll also be using the Branches and Merges functions of Git - mostly through the Bitbucket interface (and as such, with Pull Requests instead of Merges).
Bitbucket
As said in intro, we're using bitbucket because we're using bitbucket. You can use Gitlab, Gitea, whatever - but this guide is for bitbucket. If you're using GitHub... why aren't you using DevOps Center ?
Bitbucket, much like Salesforce, is a cloud solution. It is part of the Atlassian cloud offering, which also hosts JIRA, which we'll be configuring as well. You'll need to authenticate to your workspace (maybe get your Administrator to get you logins), in the format https://bitbucket.org/myworkspace
You will see that Bitbucket is a Git Server that contains Git Repositories.
In short, it is the central place where we'll host the different project repositories that we are going to use.
Built on top of the Git server are also subordinate functions such as Pull Requests, Deployments, Pipelines - which we're all going to use.
Seeing as we want this to be connected with our Atlassian cloud, we'll also ask you to go to https://bitbucket.org/account/settings/app-passwords/ which allows you to create application passwords, and to create one for Git.
In detail:
- Repositories: Developers store their Salesforce metadata and code in Bitbucket repositories. Each repository can represent a project or a component of a larger Salesforce application.
- Branching: Developers create branches for new features, bug fixes, or enhancements. This allows multiple developers to work on different parts of the codebase simultaneously without interfering with each other.
- Pull Requests: When a feature or bug fix is complete, a pull request is created. Other team members review the changes before they are merged into the main branch, ensuring code quality and consistency.
- Commits: Developers commit their changes to Bitbucket, providing a detailed commit message. These messages often include references to JIRA ticket numbers (e.g., "Fixed bug in login flow [JIRA-123]").
- JIRA: When a commit message includes a JIRA ticket number, JIRA can automatically update the status of the ticket, link the commit to the ticket, and provide traceability from issue identification to resolution.
- Pipelines: Bitbucket Pipelines can be configured to automatically build, test, and deploy Salesforce code changes. This ensures that changes are validated before being merged and deployed to production. It does so using Deployments - which in bitbucket means "the installation of code on a remote server", in our case Salesforce.
Extra Stuff
SGD
SGD, or Salesforce-Git-Delta is a command line plugin that allows the CLI to automatically generate a package.xml and a destructivechanges.xml based on the difference between two commits.
It allows you to do in Git what the CLI does alone using Source Tracking.
Why is it useful then ? Because Source Tracking is sometimes buggy, and also because in this case we're using Bitbucket, so it makes generating these deployment files independent from our machines.
SGD is very useful for inter-org deployment, which should technically be quite rare.
SFDMU
SFDMU, or the Salesforce Data Move Utility, is another command line plugin which is dataloader on steroids for when you want to migrate data between orgs or back stuff up to CSVs.
We use this because it allows migrating test data or config data (that last one should be VERY rare what with the presence of CMTD now) very easily including if you have hierarchies (Contacts of Accounts, etc).
Chapter 3: Basic Machine Setup
1 - Install Local Software
If you are admin on your machine, download Visual Studio Code from this link. Otherwise, use whatever your IT has to install software, whether it be Software Center, opening a ticket, or anything else of that ilk.
As long as you're doing that, you can also install a JDK like AZUL, as well as Git, and a nice terminal emulator.
Also remember to install the Salesforce CLI.
These elements are all useful down the line, and doing all the setup at once avoids later issues.
2 - Configure the CLI
Opening your beautiful terminal emulator, run
sf update
You should see @salesforce/cli: Updating CLI
run for a bit.
If you see an error saying sf
is not a command or program, something went wrong during the installation in step 1. Contact your IT (or check the installation page of the CLI if you're Admin or not in an enterprise context).
Once that's done, run
sf plugins install sfdmu sfdx-git-delta
Because sgd is not signed, you will get a warning saying that "This plugin is not digitally signed and its authenticity cannot be verified". This is expected, and you will have to answer y
(yes) to proceed with the installation.
Once you've done that, run:
git config --global user.name "FirstName LastName"
replacing Firstname and Lastname with your own.
git config --global user.email "email@server.tld"
replacing the email with yours
If you're running Windows - git config --global core.autocrlf true
If you're running Mac or Linux - git config --global core.autocrlf input
The above commands tell git who you are, and how to handle line endings.
All of this setup has to be done once, and you will probably never touch it again.
Finally, run
java --version
If you don't see an error, and you see something like openjdk 21.0.3 2024-04-16 LT
then you installed Zulu properly and you're fine.
3 - Configure VSCode
Open up VSCode.
Go to the Extensions in the side panel (it looks like three squares) and search for "Salesforce", then install
- Salesforce Extensions Pack
- Salesforce Extensions Pack (Expanded)
- Salesforce Package.xml Generator for VS Code
- Salesforce CLI Command Builder
- Salesforce XML Formatter
Then search for Atlassian and install "Jira and Bitbucket (Atlassian Labs)".
Finally, search for and install "GitLens - Git supercharged".
Then go to Preferences > Settings > Salesforcedx-vscode-core: Detect Conflicts At Sync and check this checkbox.
Once all this is done, I recommend you go to the side panel, click on Source Control, and drag-and-drop both the Commit element and the topmost element to the right of the editor.
All this setup allows you to have more visual functions and shortcuts. If you fail to install some elements, it cannot be guaranteed that you will have all the elements you are supposed to.
This concludes basic machine setup.
All of this should not have to be done again on an already configured machine.
Chapter 4 - Base Project Setup
SFDX Create Project
Btibucket Create repo
Git Init Repo
Set Origin Remote
Set Origin Branch
Set Repo Branches
Set JIRA