Skip to content

Deployment ​

Reusable workflow that deploys Salesforce metadata to a target org (sandbox or production). Supports a dry-run (validation only) mode, delta deployments, anonymous Apex post-deploy scripts and the Agentforce agents of the project.

Reusable workflow - call it from your own repository with uses:. View source

Inputs ​

InputDescriptionTypeRequiredDefault
source-dirSource directory to deploy.stringnoforce-app
build-scriptOptional npm script to run from the repository root before the deployment, e.g. "build:ui-bundles" to build the UI bundles of a Multi-Framework project. It runs with the package manager of the repository and with SF_TARGET_ORG set to the target org. Leave empty to skip.stringno-
target-org-aliasAlias used for the authenticated target org.stringnotarget-org
test-levelApex test level for the deployment. Ignored when apex-tests is set.stringnoRunLocalTests
apex-testsComma-separated or multi-line list of Apex test classes to run during the deployment. A selection always runs with RunSpecifiedTests. Leave empty to run the test-level.stringno-
dry-runValidate the deployment without saving the components (check-only).booleannofalse
deltaDeploy only the components changed since delta-from.booleannofalse
delta-fromGit ref to compare from when delta is enabled, e.g. a previous release tag.stringno-
apex-file-pathComma-separated anonymous Apex file(s) or glob(s) to execute after a successful deployment, e.g. "./scripts/apex/post-deploy/*.apex". Skipped on a dry-run. Leave empty to skip.stringno-
deploy-agentsBring the Agentforce agents found in source-dir to the org after the deployment - publish and activate them, then deploy their tests. On a dry-run, their Agent Script is only validated. A project without agents skips this.booleannotrue
activate-agentsActivate the agent versions after publishing. Set to false to leave the currently active versions in place.booleannotrue
agent-post-publish-dirComma-separated or multi-line list of source directories to deploy once the agents exist, e.g. permission sets granting access to an agent. Keep them outside of source-dir. Leave empty to skip.stringno-
agent-testsRun the agent tests of the project against the org. Opt-in, because they consume Einstein Requests or Flex Credits and can change org data. Needs deploy-agents. A project without agent tests skips this.booleannofalse
agent-test-namesComma-separated or multi-line list of agent tests to run instead of all tests of the project. Leave empty to run all.stringno-
environmentOptional GitHub Environment to run in - enables protection rules (required reviewers) and environment-scoped secrets. Leave empty to run without one.stringno-
refOptional branch, tag or commit SHA to check out and deploy, e.g. an environment branch for a scheduled full validation, or a release tag. Leave empty to deploy the ref that triggered the workflow.stringno-

Secrets ​

SecretDescriptionRequired
SFDX_CONSUMER_KEYConsumer key (client ID) of the connected app used for the JWT flow.yes
SFDX_JWT_SECRET_KEYContents of the private server key (server.key) used for the JWT flow.yes
SFDX_USERNAMEUsername of the integration user to authenticate as.yes

Example usage ​

Copy this caller into your project's .github/workflows/ directory (source):

yaml
# Example: call the reusable deployment workflow.
# Copy this file into your project's .github/workflows/ directory.

name: Deployment

on:
  push:
    branches: [main]
  workflow_dispatch:

# Least-privilege token: the called workflow only reads the repository and talks
# to Salesforce. A reusable workflow can never get more permissions than the
# caller grants here.
permissions:
  contents: read

jobs:
  deploy:
    uses: svierk/salesforce-devops-starter-kit/.github/workflows/deployment.yml@v1.8.0
    with:
      source-dir: force-app
      # Build what the deploy needs but Git does not hold, e.g. the UI bundles
      # of a Multi-Framework project - an npm script in your root package.json:
      # build-script: build:ui-bundles
      target-org-alias: production
      test-level: RunLocalTests
      # Run only a selection of Apex test classes instead (implies RunSpecifiedTests):
      # apex-tests: AccountServiceTest,LeadServiceTest
      dry-run: false
      # Gate this deployment behind a GitHub Environment (required reviewers,
      # environment-scoped secrets). Create it under Settings → Environments and
      # store the production credentials there. Remove to deploy without one.
      environment: production
      # For an incremental deployment of changed components only:
      # delta: true
      # delta-from: <previous release tag or commit>
      # Anonymous Apex post-deploy scripts (data migrations, cache clearing, ...),
      # executed in alphabetical order after a successful, non-dry-run deployment:
      # apex-file-path: ./scripts/apex/post-deploy/*.apex
      # Agentforce agents in source-dir are published and activated automatically.
      # Run their tests against this org as well (consumes credits, can change data):
      # agent-tests: true
    secrets:
      SFDX_CONSUMER_KEY: ${{ secrets.SFDX_CONSUMER_KEY }}
      SFDX_JWT_SECRET_KEY: ${{ secrets.SFDX_JWT_SECRET_KEY }}
      SFDX_USERNAME: ${{ secrets.SFDX_USERNAME }}

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