Environment variables
Every environment variable the toolchain reads is resolved in one place — utils/env.mjs — and
task scripts import the semantic exports rather than touching process.env themselves. Set the
consumer-facing ones as repository variables unless noted otherwise.
How booleans are parsed
Toggles accept 1, true, or yes (case-insensitive) as "on"; everything else, including
unset, 0, false, no, means "off". Scripts always write the canonical true.
Authentication
| Variable |
Effect |
<ENV>_AUTH_URL |
SFDX auth URL for a stage org, e.g. SIT_AUTH_URL, UAT_AUTH_URL, PRODUCTION_AUTH_URL. |
DEVHUB_AUTH_URL |
SFDX auth URL for the DevHub (pooling, scratch orgs). |
BITBUCKET_ACCESS_TOKEN |
Repository access token for the Bitbucket REST calls that publish commit build statuses. |
Delta and validation opt-ins
| Variable |
Effect |
DELTA_DEPLOY_<NAME> |
Enable delta deploys when <NAME> is the run's deployment environment or PR target branch (last segment, uppercased); the source branch is not matched. DELTA_DEPLOY_SCRATCH enables pooled-delta validation. |
DELTA_STAGE |
A step self-names its stage for exclusive matching (scratch-create sets SCRATCH). |
SCRATCH_ORG_VALIDATION_<NAME> |
Opt a stage into pooled scratch-org validation for its PRs. |
DISABLE_SCRATCH_ORG_VALIDATION |
Global kill switch for the scratch-validation step — wins over everything. |
SCRATCH_ORG_VALIDATION_SKIP_WITHOUT_METADATA |
Skip scratch validation for PRs touching neither force-app nor .forceignore. |
Deploy behaviour
| Variable |
Effect |
SF_DEPLOY_ENABLED |
Must be truthy in CI, or the orchestrator prepares metadata and exits 0 (a dry run). |
SF_DEPLOY_TARGET |
Drives replaceWhenEnv value replacements in sfdx-project.json (see how to replace a value per environment); defaults to ENVIRONMENT or SIT. |
TEST_LEVEL |
Apex test level for full deploys (default RunLocalTests). See how to control which Apex tests run on a full deploy. |
TESTS |
Space-separated Apex classes for RunSpecifiedTests. |
TEST_SUITE_NAMES |
Suite name(s) for RunSpecifiedTestSuites (converted to a class list). |
SF_ORG_METADATA_REST_DEPLOY |
Read by the sf CLI, not by the scripts: true switches sf project deploy from SOAP to the REST Metadata API. Required once a full package exceeds the SOAP request cap of 50 MB (error soapenv:Client: Maximum size of request reached); scratch-org pushes set it themselves. |
DEBUG |
Verbose output across the scripts (also -D/--debug per command). The only debug variable. |
| Variable |
Effect |
PoolTag |
Pipeline variable naming the pool a Maintain/Cleanup run acts on (passed as --tag). |
BASE64_BOT_PRIVATE_KEY |
Base64 SSH private key the git bot uses to push back (ci auth-gitbot). |
PACKAGE_ALIAS |
Default package for package-version-create when no --package-alias is given. |
VERSION / SEMANTIC_RELEASE_VERSION |
Version string surfaced in pool-command help output. |
Derived values (not set by you)
ENVIRONMENT (coarse stage: SIT/UAT/PRODUCTION, from the Bitbucket deployment environment or
the PR target branch) and SF_DEPLOY_TARGET are computed in utils/env.mjs. The BITBUCKET_*
pipeline context (BITBUCKET_COMMIT, BITBUCKET_PR_DESTINATION_BRANCH, BITBUCKET_BRANCH, …) and
CI-detection variables are read there too and exposed as semantic exports. Why the reads are
confined to that one module:
the shared library.
Exit-code conventions
| Code |
Meaning |
| 0 |
Success (or a dry run where SF_DEPLOY_ENABLED was not set). |
| 1 |
Generic failure, including usage errors (missing/invalid arguments). |
| 4 |
Configuration / definition error (bad pool def, unknown plugin, missing required file). |
| 21 |
Deterministic Apex-test-only failure — the deploy will not be retried. See the delta ladder. |