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
| Input | Description | Type | Required | Default |
|---|---|---|---|---|
source-dir | Source directory to deploy. | string | no | force-app |
build-script | Optional 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. | string | no | - |
target-org-alias | Alias used for the authenticated target org. | string | no | target-org |
test-level | Apex test level for the deployment. Ignored when apex-tests is set. | string | no | RunLocalTests |
apex-tests | Comma-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. | string | no | - |
dry-run | Validate the deployment without saving the components (check-only). | boolean | no | false |
delta | Deploy only the components changed since delta-from. | boolean | no | false |
delta-from | Git ref to compare from when delta is enabled, e.g. a previous release tag. | string | no | - |
apex-file-path | Comma-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. | string | no | - |
deploy-agents | Bring 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. | boolean | no | true |
activate-agents | Activate the agent versions after publishing. Set to false to leave the currently active versions in place. | boolean | no | true |
agent-post-publish-dir | Comma-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. | string | no | - |
agent-tests | Run 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. | boolean | no | false |
agent-test-names | Comma-separated or multi-line list of agent tests to run instead of all tests of the project. Leave empty to run all. | string | no | - |
environment | Optional GitHub Environment to run in - enables protection rules (required reviewers) and environment-scoped secrets. Leave empty to run without one. | string | no | - |
ref | Optional 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. | string | no | - |
Secrets
| Secret | Description | Required |
|---|---|---|
SFDX_CONSUMER_KEY | Consumer key (client ID) of the connected app used for the JWT flow. | yes |
SFDX_JWT_SECRET_KEY | Contents of the private server key (server.key) used for the JWT flow. | yes |
SFDX_USERNAME | Username 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 }}