Skip to content

🚀 SFDX Deploy ​

This repository implements a simple GitHub composite action for deploying Salesforce metadata to a target org. It supports source directories, manifest (package.xml) and metadata component selectors, configurable Apex test levels, validation-only (--dry-run) deployments, and optional delta deployments (only the components that changed between two git refs) via the sfdx-git-delta plugin - which makes it equally suitable for pull request validation and for the actual deployment to higher environments.

Usage ​

Validate a deployment on pull requests (dry-run) ​

After installing the SF CLI and authorizing the relevant org, a check-only validation could look like this:

Check out with fetch-depth: 0 so metadata deletions can be detected (see Deleting metadata). Set destructive-changes: false if you don't need this - then a shallow checkout is fine.

yaml
# Validate pull requests with `pull_request`, never `pull_request_target` - the
# latter would run fork code with this repository's org credentials.
on:
  pull_request:
    branches: [main]

# Least-privilege token: this pipeline only reads the repository.
permissions:
  contents: read

jobs:
  validation:
    name: Validation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false # don't leave the GITHUB_TOKEN in .git/config for later steps

      - name: Install SF CLI
        uses: svierk/sfdx-cli-setup@v1.2.0

      - name: Salesforce Org Login
        uses: svierk/sfdx-login@v1.4.3
        with:
          sfdx-url: ${{ secrets.SFDX_AUTH_URL }}
          alias: target-org

      - name: Validate Deployment
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          source-dir: force-app
          target-org: target-org
          test-level: RunLocalTests
          dry-run: true

Deploy metadata to an org ​

yaml
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0            # required so metadata deletions can be detected
          persist-credentials: false

      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          source-dir: force-app
          target-org: target-org
          test-level: RunLocalTests

List inputs (comma-separated or multi-line) ​

The list inputs - source-dir, metadata and tests - accept a comma-separated string as well as a multi-line block, and the two notations can be mixed freely within one step. A comma-separated string keeps short lists on a single line, a block stays readable once a list grows:

yaml
      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          source-dir: 'force-app,my-other-app' # comma-separated
          tests: | # multi-line block
            AccountServiceTest
            OpportunityServiceTest
            LeadConversionTest
          target-org: target-org
          test-level: RunSpecifiedTests

Surrounding whitespace and blank lines are ignored, so 'force-app, my-other-app' is read exactly like the tightly packed 'force-app,my-other-app'. Whitespace inside a value is kept, e.g. for a layout like Layout:Account-Account Layout.

Delta deployment (only changed components) ​

Delta mode uses sfdx-git-delta to deploy only the components that changed between two git refs. This requires the full git history, so check out with fetch-depth: 0. The generated delta manifest takes precedence over source-dir, manifest and metadata, and component deletions are applied as post-destructive changes (see Deleting metadata). If no deployable changes are detected, the step succeeds without deploying.

The action writes the generated manifests to changed-sources/ and removes the source copies that sfdx-git-delta creates there, so later steps such as a SonarQube scan don't count them as source code.

yaml
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Deploy Changed Components
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          delta: true
          delta-from: origin/${{ github.base_ref }}
          delta-to: HEAD
          target-org: target-org
          test-level: RunLocalTests

Deleting metadata (destructive changes) ​

A plain Salesforce source deploy is additive - it never deletes a component from the org just because its file was removed from the repo. This action improves on that: it detects metadata you deleted in the repository (via sfdx-git-delta) and applies those deletions to the target org after the deployment, for both delta and normal full deployments. This behaviour is on by default (destructive-changes: true); set it to false for an additive-only deploy.

yaml
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0            # required so deletions can be detected
          persist-credentials: false

      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          source-dir: force-app
          target-org: target-org
          test-level: RunLocalTests
          # destructive-changes: true  # default - components deleted in the repo are deleted on the org

How it works:

  • Deletions are derived from the git range delta-from..delta-to. In a full deployment delta-from defaults to the previous commit (HEAD~1) and delta-to to HEAD; set delta-from explicitly (e.g. a base branch or release tag) to compare against a different baseline.
  • The full git history is required (fetch-depth: 0). On a shallow clone deletions cannot be detected and the action emits a warning instead of deleting.
  • Everything runs as a single, atomic deploy (one test run): when deletions exist the action deploys via a generated package.xml plus the derived destructiveChanges.xml, since Salesforce requires post-destructive changes to be paired with a manifest.
  • With dry-run: true the deletions are validated (check-only) but not applied.
  • Files matched by the project's .forceignore or by exclude are neither deployed nor deleted.

Keeping components from being deleted ​

Some components should be deployed but never deleted by a pipeline, e.g. flows, whose deletion fails while a version is active. List them in destructive-exclude, in .forceignore syntax. Unlike exclude, the components are still deployed:

yaml
      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          source-dir: force-app
          target-org: target-org
          destructive-exclude: |
            **/*.flow-meta.xml
            **/*.flowDefinition-meta.xml

The log and the job summary list the deletions held back this way, so that they can be done by hand where needed. Record types don't need an entry: sfdx-git-delta never puts them into the destructive changes, as the Metadata API can't delete them.

InputDeployedDeleted
excludenono
destructive-excludeyesno

Project in a subfolder ​

The Salesforce CLI only deploys from inside a project, the folder holding sfdx-project.json. By default the action runs at the root of the workspace. If the project lives in a subfolder, set working-directory to it, as working-directory on the step itself only applies to run steps, not to an action:

yaml
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          path: projects/crm
          fetch-depth: 0
          persist-credentials: false

      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.6.0
        with:
          working-directory: projects/crm
          source-dir: force-app
          target-org: target-org
  • The action runs in that folder, so source-dir, manifest, the patterns in exclude and destructive-exclude, and the generated changed-sources/ and generated-manifest/ folders are relative to it, just like the project's .forceignore.
  • It works both for a repository checked out into a subfolder, as above, and for a project in a subfolder of a monorepo. In a monorepo, the delta and the deletions only cover the changes inside the project folder, and the API version comes from the project's sfdx-project.json.
  • Without a sfdx-project.json in the folder, the step fails with a hint to this input.

Inputs ​

NameRequiredDefaultDescription
working-directoryno.Folder of the Salesforce project (holding sfdx-project.json), relative to the workspace. All other paths are relative to it. See Project in a subfolder.
source-dirnoSource directories to deploy, comma-separated or multi-line.
manifestnoPath to a manifest (package.xml) file specifying the components to deploy.
metadatanoMetadata component names, comma-separated or multi-line, e.g. ApexClass,CustomObject:Account.
destructive-changesnotrueAuto-detect metadata deleted in the repo (via sfdx-git-delta) and delete it on the org after the deploy. Works for full and delta deployments. Needs fetch-depth: 0. Set false for additive-only.
excludenoPatterns to leave out of this deployment, comma-separated or multi-line in .forceignore syntax. They apply on top of the project's .forceignore, which is restored afterwards. See SFDX Agent Deploy.
destructive-excludenoPatterns of components that are never deleted from the org, comma-separated or multi-line in .forceignore syntax. Unlike exclude, they are still deployed. See Keeping components from being deleted.
deltanofalseDeploy only components changed between two git refs (via sfdx-git-delta). Needs fetch-depth: 0.
delta-fromnoGit ref to compare from when detecting changes/deletions, e.g. origin/main. Required in delta mode; defaults to HEAD~1 for destructive changes on full deployments.
delta-tonoHEADGit ref to compare to when detecting changes/deletions.
target-orgnoUsername or alias of the target org. Not required if the default org is set.
test-levelnoNoTestRun, RunSpecifiedTests, RunLocalTests or RunAllTestsInOrg.
testsnoApex tests for the RunSpecifiedTests level, comma-separated or multi-line.
dry-runnofalseValidate the deployment without saving components (check-only deployment).
ignore-conflictsnofalseDeploy local files even if they overwrite changes in the org.
ignore-warningsnofalseAllow the deployment to complete successfully despite warnings.
waitno33Number of minutes to wait for the deployment to complete.
api-versionnoOverride the api version used for api requests, for example 68.0.
step-summarynotrueWrite a result section to the GitHub Actions job summary. Set to false to avoid collisions with a custom workflow summary.

When the tests input is provided, the CLI runs the specified tests and the test-level input is ignored.

If none of source-dir, manifest or metadata is provided (and delta mode is off), the CLI deploys the package directories defined in your sfdx-project.json (typically force-app).

Outputs ​

NameDescription
deploy-idID of the deployment job.
statusFinal status of the deployment (e.g. Succeeded).

The step fails if the deployment fails, while still printing the deployment result and setting the outputs.

The action prints a concise, human-readable table of the affected components (created, changed and deleted) to the log and folds a detailed, human-readable breakdown of the deployment result - including component errors, test failures and code coverage warnings - into a collapsible "Deployment details" group (or "Validation details" for dry-runs). When step-summary is enabled, the job summary additionally lists the deployed, modified and deleted metadata - including deletions applied via destructive changes and those held back by destructive-exclude - plus a failures table when the deployment did not succeed.

Which components are listed as changed ​

Salesforce reports every LWC and Aura bundle as changed on every deployment, even when the deployed files are byte for byte what the org already has. The action corrects this: it reads these bundles from the org before the deployment and compares them with the deployed files afterwards. Only bundles that really differ are listed, including those with an added or removed file. The log and the job summary state how many bundles were left out this way.

  • This takes one additional retrieve, limited to the LWC and Aura bundles of the project, so it depends on the size of the project, not of the org. Bundles in the org that the project doesn't contain are not read. Projects without bundles skip the retrieve. If it fails, the deployment continues as usual, a notice is shown and the list contains the bundles as Salesforce reports them.
  • Only the list and its counts change. The bundles are still part of the deployment.
  • The .md files of a bundle don't count, as the org doesn't store them. A change to a component's README is therefore not a change to the component.

For all other metadata types the list shows what Salesforce reports, which proved reliable: a component that matches the org is not listed. Two cases can still be surprising:

  • Formatting. Salesforce stores LWC, Aura and Apex source as it is deployed, so formatting with Prettier doesn't cause differences by itself. Reformatting an existing file is a real change to the text in the org, and is listed once. Whitespace in XML metadata doesn't count.
  • XML metadata that Salesforce normalizes. The org adds default values to some types, or changes values such as the canvas position in a Flow. A file that was written by hand or in another tool may never match, and is then listed on every deployment. To resolve this, retrieve the component once and commit the result. Formatting it with Prettier afterwards is fine.

Security & versioning ​

Every uses: reference in the snippets above is pinned to an exact release version, e.g. svierk/sfdx-deploy@v1.6.0. Do the same in your own pipelines:

  • Never reference a mutable ref such as @main or @v1. It runs whatever code sits on that branch/tag at run time - with access to your org credentials - so a compromised or rewritten ref would run unnoticed.
  • Good - pin to an exact release tag (@v1.6.0). Readable, concrete, and bumped through reviewed pull requests.
  • Strictest - pin to a full-length commit SHA (@a1b2c3d…) with the version as a trailing comment. A SHA can never be re-pointed by the publisher; the cost is readability. Worth it for actions from publishers you don't control.
  • Enable Dependabot for github-actions so those pins are bumped for you instead of silently ageing. Note that Dependabot only scans .github/workflows and a root action.yml - copy-paste snippets in a README are not covered and have to be updated by hand.

This applies to all actions your workflows reference - this action as well as actions/* and any other third-party action. Latest versions at the time of writing: actions/checkout@v7.0.1, svierk/sfdx-cli-setup@v1.2.0, svierk/sfdx-login@v1.4.3, svierk/sfdx-deploy@v1.6.0.

Beyond pinning, a few rules are worth copying into the workflow that calls this action:

  • Least-privilege GITHUB_TOKEN - declare a permissions: block granting only what the job needs. This action itself needs no token at all, so contents: read is enough for the deploy job.
  • persist-credentials: false on checkout - the token is not written to .git/config, so later steps (SF CLI, third-party actions) cannot reuse it. The delta and destructive-change detection reads the local git history only and works fine without persisted credentials.
  • Secrets travel as secrets - pass them straight into an action input (sfdx-url: ${{ secrets.SFDX_AUTH_URL }}) and reference them in your own shell steps as environment variables ("$TARGET_ORG"), never by interpolating ${{ ... }} into the script itself - that would allow command injection and can leak values into the log. Every input of this action is handed to the shell through an env: mapping for exactly that reason.
  • Validate pull requests with pull_request, never pull_request_target - the latter runs with the base repository's secrets, which would let a fork execute its own code against your org.
  • Gate production behind a GitHub Environment - required reviewers and environment-scoped secrets keep a non-dry-run deploy from being triggered accidentally.

References ​

The deployment option supported by this GitHub composite action can be found in the Salesforce CLI Command Reference here:

Releases ​

Latest release notes can be found on the release page.

License ​

The scripts and documentation in this project are released under the MIT License.


➡️ Full source & releases: svierk/sfdx-deploy

Released under the MIT License. · llms.txt for AI agents