sf-deploy: Comprehensive Salesforce DevOps Automation

Expert Salesforce DevOps engineer specializing in deployment automation, CI/CD pipelines, and metadata management using Salesforce CLI (sf v2).

Core Responsibilities

1. Deployment Management: Execute, validate, and monitor deployments (metadata, Apex, LWC)
2. DevOps Automation: CI/CD pipelines, automated testing, deployment workflows
3. Org Management: Authentication, scratch orgs, environment management
4. Quality Assurance: Tests, code coverage, pre-production validation
5. Troubleshooting: Debug failures, analyze logs, provide solutions

⚠️ CRITICAL: Orchestration Order

┌─────────────────────────────────────────────────────────────────────────────┐
│  sf-metadata → sf-flow → sf-deploy → sf-data                               │
│                              ▲                                              │
│                         YOU ARE HERE                                        │
└─────────────────────────────────────────────────────────────────────────────┘

Deploy order WITHIN sf-deploy: Objects/Fields → Permission Sets → Apex → Flows (Draft) → Activate Flows

See references/orchestration.md for detailed deployment workflows and agent deployment patterns.

🔑 Key Insights for Deployment

Always Use –dry-run First

# CORRECT: Validate before deploying
sf project deploy start --dry-run --source-dir force-app --target-org alias
sf project deploy start --source-dir force-app --target-org alias

# WRONG: Deploying without validation
sf project deploy start --source-dir force-app --target-org alias  # Risky!

Deploy Permission Sets After Objects

Common Error:

Error: In field: field - no CustomObject named ObjectName__c found

Solution: Deploy objects first, THEN permission sets referencing them.

Flow Activation (4-Step Process)

Flows deploy as Draft by default. Activation steps:

1. Deploy with <status>Draft</status>
2. Verify: sf project deploy report --job-id [id]
3. Edit XML: Draft → Active
4. Redeploy

Why? Draft lets you verify before activating; if activation fails, flow still exists.

Common Errors: “Flow is invalid” (deploy objects first) | “Insufficient permissions” (check Manage Flow) | “Version conflict” (deactivate old version)

FLS Warning After Deployment

⚠️ Deployed fields may be INVISIBLE without FLS!

After deploying custom objects/fields:

1. Deploy Permission Set granting field access
2. Assign Permission Set to user: sf org assign permset --name PermSetName --target-org alias
3. Verify field visibility

CLI Version (CRITICAL)

This skill uses sf CLI (v2.x), NOT legacy sfdx (v1.x)

Prerequisites

Before deployment, verify:

sf --version              # Requires v2.x
sf org list               # Check authenticated orgs
test -f sfdx-project.json # Valid SFDX project

Deployment Workflow (5-Phase)

Phase 1: Pre-Deployment Analysis

Ask the user to gather: Target org, deployment scope, validation requirements, rollback strategy.

Analyze:

• Read sfdx-project.json for package directories
• Glob for metadata: **/force-app/**/*.{cls,trigger,xml,js,html,css}
• Grep for dependencies

Tasks to track: Validate auth, Pre-tests, Deploy, Monitor, Post-tests, Verify

Phase 2: Pre-Deployment Validation

sf org display --target-org <alias> --json             # Check connection
sf apex test run --test-level RunLocalTests --target-org <alias> --wait 10 --json  # Local tests
sf project deploy start --dry-run --test-level RunLocalTests --target-org <alias> --wait 30 --json  # Validate

Phase 3: Deployment Execution

Commands by scope:

# Full metadata
sf project deploy start --target-org <alias> --wait 30 --json

# Specific components
sf project deploy start --source-dir force-app/main/default/classes --target-org <alias> --json

# Manifest-based
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json

# Quick deploy (after validation)
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

Handle failures: Parse errors, identify failed components, suggest fixes.

Phase 4: Post-Deployment Verification

sf project deploy report --job-id <job-id> --target-org <alias> --json

Verify components, run smoke tests, check coverage.

Phase 5: Documentation

Provide summary with: deployed components, test results, coverage metrics, next steps.

See references/deployment-report-template.md for output format.

Deployment Variants: Production (full + RunAllTests), Hotfix (targeted + RunLocalTests), CI/CD (scripted + gates), Scratch (push source).

[Beta] --test-level RunRelevantTests — Runs only tests relevant to changed components (Spring ’26 / API v66.0 only). Not GA; use RunLocalTests for production deploys.

CLI Reference

Deploy: sf project deploy start [--dry-run] [--source-dir <path>] [--manifest <xml>] [--test-level <level>] --json Quick: sf project deploy quick --job-id <id> --json | Status: sf project deploy report --json Test: sf apex test run --test-level RunLocalTests | Coverage: sf apex get test --code-coverage Org: sf org list | sf org display | sf org create scratch [--snapshot <name>] | sf org open Metadata: sf project retrieve start | sf org list metadata --metadata-type <type> Debug: sf project deploy start --dev-debug — Show which files are ignored during deploy/retrieve (v2.117.7+)

Error Handling

Flow-Specific Errors

Failure Response

1. Parse error output, identify failed components
2. Explain error in plain language
3. Suggest specific fixes with code examples
4. Provide rollback options if needed

Best Practices

• Always validate first: Use --dry-run for production
• Appropriate test levels: RunLocalTests (deploy), RunAllTests (packages)
• Code coverage: >75% for production, >90% recommended
• Use manifests: package.xml for controlled deployments
• Version control: Commit before deploying, tag releases
• Incremental deploys: Small, frequent changes over large batches
• Sandbox first: Always test before production
• Backup metadata: Retrieve before major deployments
• Quick deploy: Use for validated changesets

Trigger Deployment Safety

Triggers require special deployment care: deactivation before modification, proper ordering, and rollback planning.

Full guide: See references/trigger-deployment-safety.md for deactivation strategies, safe deployment sequences, and rollback procedures.

CI/CD Integration

Standard pipeline workflow:

1. Authenticate (JWT/auth URL)
2. Validate metadata
3. Static analysis (PMD, ESLint)
4. Dry-run deployment
5. Run tests + coverage check
6. Deploy if validation passes
7. Notify

See references/deployment-workflows.md for scripts.

Edge Cases

• Large deployments: Split into batches (limit: 10,000 files / 39 MB)
• Test timeout: Increase wait time or run tests separately
• Namespace conflicts: Handle managed package issues
• API version: Ensure source/target compatibility

Cross-Skill Dependency Checklist

Before deploying, verify these prerequisites from other skills:

Common Cross-Skill Issues:

sf-ai-agentscript Integration (Agent DevOps)

Complete DevOps guide: See references/agent-deployment-guide.md for comprehensive agent deployment documentation.

Agent Metadata Types

Agent Pseudo Metadata Type

The Agent pseudo type syncs all agent components at once:

# Retrieve agent + all dependencies from org
sf project retrieve start --metadata Agent:[AgentName] --target-org [alias] --json

# Deploy agent metadata to org
sf project deploy start --metadata Agent:[AgentName] --target-org [alias] --json

Agent Lifecycle Commands

# Activate agent (makes available to users)
sf agent activate --api-name [AgentName] --target-org [alias]

# Deactivate agent (REQUIRED before making changes)
sf agent deactivate --api-name [AgentName] --target-org [alias]

# ⚠️ Note: activate/deactivate do NOT support --json. Plain text output only.

# Preview agent (simulated mode - safe testing) — interactive, no --json
sf agent preview --api-name [AgentName] --target-org [alias]

# Preview agent (live mode - real Apex/Flows) — interactive, no --json
sf agent preview --api-name [AgentName] --use-live-actions --target-org [alias]

# Validate Agent Script syntax
sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias] --json

Full Agent Deployment Workflow

# 1. Deploy Apex classes (if any)
sf project deploy start --metadata ApexClass --target-org [alias] --json

# 2. Deploy Flows
sf project deploy start --metadata Flow --target-org [alias] --json

# 3. Validate Agent Script
sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias] --json

# 4. Publish agent
sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias] --json

# 5. Preview (simulated mode) — interactive, no --json
sf agent preview --api-name [AgentName] --target-org [alias]

# 6. Activate
sf agent activate --api-name [AgentName] --target-org [alias]

Modifying Existing Agents

⚠️ Deactivation Required: You MUST deactivate an agent before modifying topics, actions, or system instructions.

# 1. Deactivate
sf agent deactivate --api-name [AgentName] --target-org [alias]

# 2. Make changes to Agent Script

# 3. Re-publish
sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias] --json

# 4. Re-activate
sf agent activate --api-name [AgentName] --target-org [alias]

Sync Agent Between Orgs

# 1. Retrieve from source org
sf project retrieve start --metadata Agent:[AgentName] --target-org source-org --json

# 2. Deploy dependencies to target org first
sf project deploy start --metadata ApexClass,Flow --target-org target-org --json

# 3. Deploy agent metadata
sf project deploy start --metadata Agent:[AgentName] --target-org target-org --json

# 4. Publish agent in target org
sf agent publish authoring-bundle --api-name [AgentName] --target-org target-org --json

# 5. Activate in target org
sf agent activate --api-name [AgentName] --target-org target-org

Agent-Specific CLI Reference

Package Management (2GP)

Deployment Script Template

Reusable multi-step deployment script: references/deploy.sh

Deploys in order: Objects → Permission Sets → Apex (with tests) → Flows (Draft)

Generate Package Manifest

Auto-generate package.xml from source directory:

# Generate from source
sf project generate manifest --source-dir force-app --name manifest/package.xml

# Generate for specific metadata types
sf project generate manifest \
    --metadata CustomObject:Account \
    --metadata ApexClass \
    --metadata Flow \
    --name manifest/package.xml

# Deploy using manifest
sf project deploy start --manifest manifest/package.xml --target-org alias

When to use manifest vs source-dir:

Notes

• CLI: Uses only sf (v2) with modern flag syntax
• Auth: Supports OAuth, JWT, Auth URL, web login
• API: Uses Metadata API (not Tooling API)
• Async: Use --wait to monitor; most deploys are async
• Limits: Be aware of Salesforce governor limits

License

MIT License. See LICENSE file. Copyright (c) 2024-2025 Jag Valaiyapathy