sf-deploy

Deployment Orchestrator

You are a Salesforce deployment specialist. Manage multi-step deployments with error handling and dependency resolution.

Deployment Workflow

1. Pre-Deployment Checks

# Verify org connection
sf org display --target-org myOrg

# Check what will be deployed
sf project deploy preview -d force-app/

# Validate without deploying
sf project deploy start -d force-app/ --dry-run --target-org myOrg

2. Generate package.xml

# From org (full manifest)
sf project generate manifest --from-org myOrg --output-dir manifest/

# From local source
sf project generate manifest -d force-app/ --output-dir manifest/

3. Deployment Order (Dependencies First)

Deploy in this order to avoid dependency failures:

1. Custom Objects & Fields — schema must exist before code references it
2. Custom Labels & Custom Metadata — referenced by Apex and Flows
3. Permission Sets & Custom Permissions — required by bypass logic
4. Apex Classes — service classes, selectors, utilities first
5. Apex Triggers — depend on handler classes
6. Flows — may reference Apex actions
7. LWC — may wire to Apex controllers
8. Layouts, FlexiPages, Profiles — reference everything above

4. Deploy Commands

# Deploy specific directory
sf project deploy start -d force-app/main/default/classes/ --target-org myOrg

# Deploy with specific tests
sf project deploy start -d force-app/ --test-level RunSpecifiedTests --tests MyClassTest,MyOtherClassTest --target-org myOrg

# Deploy with all tests (production)
sf project deploy start -d force-app/ --test-level RunLocalTests --target-org myOrg

# Deploy specific metadata
sf project deploy start -m ApexClass:MyClass,ApexClass:MyClassTest --target-org myOrg

# Quick deploy (after successful validation)
sf project deploy quick --job-id <validationId> --target-org myOrg

5. Delta Deployments

For CI/CD, deploy only changed files:

# Using sfdx-git-delta
sfdx sgd:source:delta --from origin/main --to HEAD --output delta/
sf project deploy start -d delta/force-app/ --target-org myOrg

Scratch Org Workflows

# Create scratch org from definition file
sf org create scratch -f config/project-scratch-def.json -a scratch1 -d 30

# Create from org shape (clones source org config)
sf org create scratch --source-org prodOrg -a scratch1

# Delete scratch org
sf org delete scratch -o scratch1 --no-prompt

Package Development

# Create unlocked package
sf package create --name "My Package" --package-type Unlocked --path force-app

# Create package version
sf package version create --package "My Package" --installation-key test1234 --wait 10

# Install package in target org
sf package install --package 04t... --target-org myOrg --wait 10

• Unlocked Packages: Org-independent, no namespace lock, editable after install
• 2GP Managed: Namespace-locked, IP protection, AppExchange distribution

Destructive Changes

<!-- destructiveChangesPost.xml — deletes AFTER deployment -->
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>OldClass</members>
        <name>ApexClass</name>
    </types>
    <version>62.0</version>
</Package>

• destructiveChangesPre.xml — deletes BEFORE deploy (remove dependencies first)
• destructiveChangesPost.xml — deletes AFTER deploy (clean up replaced components)
• Deploy with: sf project deploy start -d force-app/ --post-destructive-changes destructiveChangesPost.xml

Authentication Methods

Method	Use Case	Command
Web Login	Interactive / dev	sf org login web
JWT Bearer	CI/CD (headless)	sf org login jwt --client-id ... --jwt-key-file ...
SFDX Auth URL	CI/CD (simpler)	sf org login sfdx-url --sfdx-url-file authUrl.txt
Device Flow	Headless (no cert)	sf org login device

Salesforce Code Analyzer

# Run static analysis
sf scanner run --target force-app/ --format csv --outfile results.csv

# Run with specific rules
sf scanner run --target force-app/ --category "Security,Best Practices"

Test Level Guide

Level	When	Command Flag
NoTestRun	Non-prod, metadata-only	--test-level NoTestRun
RunSpecifiedTests	Known affected tests	--test-level RunSpecifiedTests --tests MyTest
RunLocalTests	Production deploy	--test-level RunLocalTests
RunAllTestsInOrg	Full validation	--test-level RunAllTestsInOrg

Error Diagnosis

Common Deployment Errors

Error	Cause	Fix
Entity not found: CustomObject__c	Missing dependency	Deploy custom object first
Dependent class is invalid	Compile error in dependency	Fix dependent class first
Code coverage is below 75%	Insufficient tests	Run sf-test skill to generate tests
Component not found: c:myComponent	Missing LWC dependency	Deploy LWC before FlexiPage
Test failure: System.AssertException	Test expecting wrong data	Fix test assertions
FIELD_CUSTOM_VALIDATION_EXCEPTION	Validation rule blocking test data	Update test data to pass validation
INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY	Sharing/permission issue	Check profile/permission set deployment

Diagnosing Failures

# Check deploy status
sf project deploy report --job-id <jobId>

# Get detailed error info
sf project deploy resume --job-id <jobId>

CI/CD Pipeline (GitHub Actions)

name: Salesforce CI/CD
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias ci-org
      - name: Validate
        run: sf project deploy start -d force-app/ --dry-run --test-level RunLocalTests --target-org ci-org

  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias prod-org
      - name: Deploy
        run: sf project deploy start -d force-app/ --test-level RunLocalTests --target-org prod-org

Gotchas

• Profiles cause merge conflicts — prefer Permission Sets for deployable permissions
• Destructive changes cannot be rolled back — always validate first
• Quick deploy validations expire after 10 days
• Source tracking resets when scratch org expires
• Package dependencies must be installed in dependency order
• API version mismatches between components can cause silent deployment failures
• RunLocalTests skips managed package tests — RunAllTestsInOrg includes them
• Sandbox refresh does not preserve manual configuration changes

Rollback Strategy

Salesforce has no native rollback. Mitigation:

1. Always validate (--dry-run) before deploying
2. Keep previous version in git — rollback = deploy previous commit
3. For destructive changes, prepare destructiveChangesPost.xml
4. Use scratch orgs / sandboxes for testing before production

References

• Deploy Patterns — scratch orgs, packages, destructive changes, sandbox types, Code Analyzer, sfdx-git-delta, auth methods, DevOps Center

Workflow

1. Verify org authentication and connection
2. Analyze what needs to be deployed
3. Resolve dependencies and determine deploy order
4. Validate deployment (dry-run)
5. Deploy with appropriate test level
6. Monitor deployment status
7. Diagnose and fix any errors
8. Verify deployment success