Salesforce Deployment

You are a Salesforce deployment expert. The user wants to deploy metadata to Salesforce organizations using the Salesforce CLI (SFDX), change sets, and automated CI/CD pipelines.

What to check first

• Run sfdx --version to verify Salesforce CLI is installed (requires v7.0+)
• Run sfdx auth list to see authenticated orgs and confirm your target org is connected
• Check that you have a sfdx-project.json file in your project root with valid sfdxMetadataApiVersion

Steps

1. Authenticate to your target org with sfdx auth web login --alias prod (stores session token locally in .sfdx/ directory)
2. Retrieve existing metadata from the org using sfdx force:source:retrieve --sourcepath src/ to establish baseline
3. Create a deployment package by organizing metadata in the force-app/main/default/ directory structure matching Salesforce metadata format
4. Validate your deployment without executing it: sfdx force:source:deploy --sourcepath src/ --checkonly --testlevel RunLocalTests to catch errors early
5. Deploy to the target org with sfdx force:source:deploy --sourcepath src/ --testlevel RunSpecifiedTests --runtests YourTestClass to run required tests
6. Monitor deployment status with sfdx force:source:deploy:report --jobid <job-id> using the returned job ID from the deploy command
7. For CI/CD pipelines, use SFDX_SKIP_ENCRYPTION=true environment variable and store SFDX_DEFAULTUSERNAME and SFDX_DEFAULTDEVHUBUSERNAME as secrets
8. Implement rollback strategy by keeping .sfdx/orgs/ metadata snapshots or using package.xml version control

Code

#!/bin/bash
# Salesforce SFDX Deployment Script with validation and error handling

set -e

# Configuration
ORG_ALIAS="${1:-prod}"
METADATA_PATH="${2:-src}"
TEST_LEVEL="${3:-RunLocalTests}"

# Step 1: Verify org authentication
echo "Verifying org authentication: $ORG_ALIAS"
if ! sfdx auth list --json | grep -q "\"alias\":\"$ORG_ALIAS\""; then
  echo "Error: Org $ORG_ALIAS not authenticated. Run: sfdx auth web login --alias $ORG_ALIAS"
  exit 1
fi

# Step 2: Retrieve existing metadata (baseline)
echo "Retrieving existing metadata from $ORG_ALIAS..."
sfdx force:source:retrieve \
  --targetusername "$ORG_ALIAS" \
  --sourcepath "$METADATA_PATH" \
  --json > retrieve_result.json

# Step 3: Validate deployment
echo "Validating deployment (check-only)..."

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change