How to Backup Salesforce Metadata for Free

Ever had a field created in production, that wasn’t added to your git history? Or just want some piece of mind in case the next apocalypse is coming? Backing up your Salesforce metadata is a great way of accomplishing all the above. And it has never been easier, thanks to the free tools that are now available.

Using GitHub, GitHub Actions, and the SF CLI, we can automate nightly backups of any metadata we wish. This includes:

• Apex Classes
• Flows
• Custom Fields
• Custom Objects
• And more

But before we get started, we need a few things configured.

Requirements

We need the following to backup our Salesforce metadata:

• Github Account
• Git
• SF CLI

If you don’t already have your existing Salesforce metadata inside github, you can use this template to get started.

And using this guide will help you configure exactly what you need.

Backing Up Metadata To Your Local Project

To automate metadata backup, we need to start by seeing how metadata is backed up using the SF CLI.

We need to configure our local project to use the SF CLI. If you installed the CLI for this first time, follow this guide on authenticating your Salesforce org with your machine.

Once authenticated, we can use the following command to backup Salesforce metadata to our project:

sf project retrieve start

While this is the basic command, this won’t do anything useful unless we pass one of the following flags:

• --source-dir
• --metadata
• --manifest

Each of these flags is designed to do different things

--source-dir Flag

This flag allows us to target a specific directory within our project to backup our code. This can be as specific as the force-app/main/default/classes, or as broad as force-app.

Using this flag is a great way of retrieving existing code, and getting the latest version from Salesforce.

sf project retrieve start --source-dir force-app

While this is what I recommend people to use when backing up existing code, the files NEED to exist in the git repo before running this command.

--metadata Flag

This is the next most complicated flag. If we wanted to track all custom objects and Apex classes, we could use the following command:

sf project retrieve start --metadata CustomObject ApexClass

The method above is great if users are creating metadata outside your development process.

--manifest Flag (Advanced)

The manifest.xml file is a list of metadata components we can retrieve. You can read more about how to generate this file here. If you are looking to automatically track new metadata, you will need a way of updating the package.xml.

This is still a great way of getting metadata into your local project (and how the SF Project Retrieve command works). To use, just pass in the path to the package.xml file

sf project retrieve start --manifest ~/manifest/package.xml

Authenticating Salesforce and GitHub

Now that we understand how to retrieve the metadata from production, we can automate this process. When we initially setup the SF CLI, we authenticated with our production org (or target org to pull the metadata). This saves a token that we can use inside of GitHub for CI/CD processes. This includes retrieving production metadata!

We can access this token by running the following command:

sf org display --verbose --json -o <MY_TARGET_ORG_ALIAS>

We will need the value of sfdxAuthUrl for later.

We can use this value as a secret inside of GitHub. To add a secret, perform the following inside of GitHub:

1. Navigate to Settings
2. Under Security open Secrets and variables and click on Actions
3. Press New Repository Secret
4. Enter the name as SFDX_AUTH_URL
5. Enter the secret as the sfdxAuthUrl copied above.

This URL can be used in any GitHub action, and cannot be seen by other people who have access to the repository.

Backup Automatically

To backup Salesforce metadata, we can leverage GitHub Actions to schedule syncs. First, create the following file in your Salesforce project: .github/workflows/backup-salesforce-metadata.yml

Inside this file, add the following code:

name: Backup Salesforce Metadata
on:
  schedule:
    # Scheduled to run at midnight UTC every day
    - cron: '0 0 * * *'

  # Allows manual triggering from the GitHub Actions UI
  workflow_dispatch:

jobs:
  backup_metadata:
    runs-on: ubuntu-latest
    environment: production
    steps:
      # Step 1: Checkout the repository
      - name: Checkout repository
        uses: actions/checkout@v3

      # Step 2: Use local action to perform Salesforce backup and create PR
      - name: Backup Salesforce Metadata
        uses: jawills/sf-retrieve@v1
        with:
          SFDX_AUTH_URL: ${{ secrets.SFDX_AUTH_URL }}
          SOURCE_DIR: force-app
          BRANCH_NAME: backup
          FORCE_PUSH: true
          GITHUB_USER_NAME: GITHUB_USER_NAME
          GITHUB_USER_EMAIL: GITHUB_USER_EMAIL

Inside this file, there are a few things we can configure.

• schedule - Is a cron expression that schedules when the Github Action will be ran
• BRANCH_NAME - The name of the branch you would like to backup to. This can be a separate branch like backup or the main branch main or master. NOTE: I recommend using a separate branch like backup.
• FORCE_PUSH - Force push the commit to the specified branch. Only use this if you are not using a separate branch like backup.

Additionally, we can specify one of the three parameters based on the metadata retrieval process:

• SOURCE_DIR
• METADATA
• MANIFEST

One final thing we need to do is update the Workflow permissions in Github. In your repo, go to Settings > Actions > General. Scroll down to Workflow permissions.

This should be set to Read and write permissions.

Additionally, this process supports one-off runs. We can use the action window to run these processes.

Manual Backup in GitHub

Inside the Actions tab, we can go to the Backup Salesforce Metadata action, and press Run Workflow.

This will allow for on-demand backups of your metadata.

Final Thoughts

GitHub Actions are a great way of automating developer pain-points. Keep in mind that the free tier only receives 2000 minutes per month.