| name | sf-deployment |
| description | Comprehensive Salesforce DevOps automation |
| version | 2.1.0 |
| author | Jag Valaiyapathy |
| license | MIT |
| tags | ["salesforce","devops","sfdx","deployment","ci-cd","automation","apex","metadata"] |
| allowed-tools | ["Bash","Read","Write","Edit","Grep","Glob","AskUserQuestion","TodoWrite"] |
| examples | [] |
| metadata | {"created":"2024-11-28","updated":"2025-12-02","format_version":"2.0.0","license_file":"LICENSE"} |
| dependencies | [] |
| homepage | |
| repository | |
| keywords | [] |
| test_config | {"enabled":false,"test_files":[]} |
sf-deployment: 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
- Deployment Management: Execute, validate, and monitor deployments (metadata, Apex, LWC)
- DevOps Automation: CI/CD pipelines, automated testing, deployment workflows
- Org Management: Authentication, scratch orgs, environment management
- Quality Assurance: Tests, code coverage, pre-production validation
- Troubleshooting: Debug failures, analyze logs, provide solutions
CLI Version (CRITICAL)
This skill uses sf CLI (v2.x), NOT legacy sfdx (v1.x)
| Legacy sfdx (v1) | Modern sf (v2) |
|---|
--checkonly / --check-only | --dry-run |
sfdx force:source:deploy | sf project deploy start |
Prerequisites
Before deployment, verify:
sf --version
sf org list
test -f sfdx-project.json
Deployment Workflow (5-Phase)
Phase 1: Pre-Deployment Analysis
Gather via AskUserQuestion: 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
TodoWrite tasks: Validate auth, Pre-tests, Deploy, Monitor, Post-tests, Verify
Phase 2: Pre-Deployment Validation
sf org display --target-org <alias>
sf apex test run --test-level RunLocalTests --target-org <alias> --wait 10
sf project deploy start --dry-run --test-level RunLocalTests --target-org <alias> --wait 30
Phase 3: Deployment Execution
Commands by scope:
sf project deploy start --target-org <alias> --wait 30
sf project deploy start --source-dir force-app/main/default/classes --target-org <alias>
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30
sf project deploy quick --job-id <validation-job-id> --target-org <alias>
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>
Verify components, run smoke tests, check coverage.
Phase 5: Documentation
Provide summary with: deployed components, test results, coverage metrics, next steps.
See examples/deployment-report-template.md for output format.
Deployment Pattern
Standard workflow for all scenarios:
- Verify org auth:
sf org display
- Identify scope: [full | components | hotfix | scratch]
- Validate:
sf project deploy start --dry-run
- Execute:
sf project deploy start [options]
- Verify:
sf project deploy report
Variants:
- Production: Full scope + backup + RunAllTests + documentation
- Hotfix: Targeted components + RunLocalTests + fast deploy
- CI/CD: Scripted + automated gates + notifications
- Scratch:
sf project deploy start (push source)
CLI Reference
Deploy: sf project deploy start [--dry-run] [--source-dir <path>] [--manifest <xml>] [--test-level <level>]
Quick: sf project deploy quick --job-id <id> | Status: sf project deploy report
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 | sf org open
Metadata: sf project retrieve start | sf org list metadata --metadata-type <type>
Error Handling
| Error | Cause | Solution |
|---|
| FIELD_CUSTOM_VALIDATION_EXCEPTION | Validation rule blocking | Deactivate rules or use valid test data |
| INVALID_CROSS_REFERENCE_KEY | Missing dependency | Include dependencies in deploy |
| CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY | Trigger/validation error | Review trigger logic, check recursion |
| TEST_FAILURE | Test class failure | Fix test or code under test |
| INSUFFICIENT_ACCESS | Permission issue | Verify user permissions, FLS |
Flow-Specific Errors
| Error | Cause | Solution |
|---|
| "Element X is duplicated" | Elements not alphabetically ordered | Reorder Flow XML elements |
| "Element bulkSupport invalid" | Deprecated element (API 60.0+) | Remove <bulkSupport> |
| "Error parsing file" | Malformed XML | Validate XML syntax |
Failure Response
- Parse error output, identify failed components
- Explain error in plain language
- Suggest specific fixes with code examples
- 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
CI/CD Integration
Standard pipeline workflow:
- Authenticate (JWT/auth URL)
- Validate metadata
- Static analysis (PMD, ESLint)
- Dry-run deployment
- Run tests + coverage check
- Deploy if validation passes
- Notify
See examples/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
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
