SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssf-deploy

sf-deploy

Deployment & operations

View repository

Updated 10-15 19:49

About this skill

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