Sf Deploy

sf-deploy: Comprehensive Salesforce DevOps Automation

Use this skill when the user needs deployment orchestration: dry-run validation, targeted or manifest-based deploys, CI/CD workflow advice, scratch-org management, failure triage, or safe rollout sequencing for Salesforce metadata.

When This Skill Owns the Task

Use sf-deploy when the work involves:

• sf project deploy start, quick, report, or retrieval workflows
• release sequencing across objects, permission sets, Apex, and Flows
• CI/CD gates, test-level selection, or deployment reports
• troubleshooting deployment failures and dependency ordering

Delegate elsewhere when the user is:

• authoring Apex or LWC code → [sf-apex](../sf-apex/SKILL.md), [sf-lwc](../sf-lwc/SKILL.md)
• creating metadata definitions → [sf-metadata](../sf-metadata/SKILL.md)
• building Flows → [sf-flow](../sf-flow/SKILL.md)
• doing org data operations → [sf-data](../sf-data/SKILL.md)
• authoring Agent Script logic → [sf-ai-agentscript](../sf-ai-agentscript/SKILL.md)

---

Critical Operating Rules

• Use sf CLI v2 only.
• On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as --source-dir, --metadata, or --manifest.
• Prefer --dry-run first before real deploys.
• For Flows, deploy safely and activate only after validation.
• Keep test-data creation guidance delegated to sf-data after metadata is validated or deployed.

Default deployment order

| Phase | Metadata | |---|---| | 1 | Custom objects / fields | | 2 | Permission sets | | 3 | Apex | | 4 | Flows as Draft | | 5 | Flow activation / post-verify |

This ordering prevents many dependency and FLS failures.

---

Required Context to Gather First

Ask for or infer:

• target org alias and environment type
• deployment scope: source-dir, metadata list, or manifest
• whether this is validate-only, deploy, quick deploy, retrieve, or CI/CD guidance
• required test level and rollback expectations
• whether special metadata types are involved (Flow, permission sets, agents, packages)

Preflight checks:

sf --version
sf org list
sf org display --target-org  --json
test -f sfdx-project.json

---

Recommended Workflow

1. Preflight

Confirm auth, repo shape, package directories, and target scope.

2. Validate first

sf project deploy start --dry-run --source-dir force-app --target-org  --wait 30 --json

Use manifest- or metadata-scoped validation when the change set is targeted.

3. If validation succeeds, offer the next safe workflow

After a successful validation, guide the user to the correct next action:

1. deploy now
2. assign permission sets
3. create test data via [sf-data](../sf-data/SKILL.md)
4. run tests / smoke checks
5. orchestrate multiple post-deploy steps in order

4. Deploy the smallest correct scope

# source-dir deploy
sf project deploy start --source-dir force-app --target-org  --wait 30 --json

# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org  --test-level RunLocalTests --wait 30 --json

# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org  --test-level RunRelevantTests --wait 30 --json

# quick deploy after successful validation
sf project deploy quick --job-id  --target-org  --json

5. Verify

sf project deploy report --job-id  --target-org  --json

Then verify tests, Flow state, permission assignments, and smoke-test behavior.

6. Report clearly

Summarize what deployed, what failed, what was skipped, and what the next safe action is.

Output template: [references/deployment-report-template.md](references/deployment-report-template.md)

---

High-Signal Failure Patterns

| Error / symptom | Likely cause | Default fix direction | |---|---|---| | FIELD_CUSTOM_VALIDATION_EXCEPTION | validation rule or bad test data | adjust data or rule timing | | INVALID_CROSS_REFERENCE_KEY | missing dependency | include referenced metadata first | | CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY | trigger / Flow / validation side effect | inspect automation stack and failing logic | | tests fail during deploy | broken code or fragile tests | run targeted tests, fix root cause, revalidate | | field/object not found in permset | wrong order | deploy objects/fields before permission sets | | Flow invalid / version conflict | dependency or activation problem | deploy as Draft, verify, then activate |

Full workflows: [references/orchestration.md](references/orchestration.md), [references/trigger-deployment-safety.md](references/trigger-deployment-safety.md)

---

CI/CD Guidance

Default pipeline shape:

1. authenticate
2. validate repo / org state
3. static analysis
4. dry-run deploy
5. tests + coverage gates
6. deploy
7. verify + notify

• When org policy and release risk allow it, consider --test-level RunRelevantTests for Apex-heavy deployments.
• Pair this with modern Apex test annotations such as @IsTest(testFor=...) and @IsTest(isCritical=true) as documented in sf-apex.

Static analysis now uses Code Analyzer v5 (sf code-analyzer), not retired sf scanner.

Deep reference: [references/deployment-workflows.md](references/deployment-workflows.md)

---

Agentforce Deployment Note

Use this skill to orchestrate deployment/publish sequencing around agents, but use the agent-specific skills for authoring decisions:

• [sf-ai-agentscript](../sf-ai-agentscript/SKILL.md) for .agent authoring and validation
• [sf-ai-agentforce](../sf-ai-agentforce/SKILL.md) for Agent Builder / Prompt Builder / metadata config

For full agent DevOps details, including Agent: pseudo metadata, publish/activate, and sync-between-orgs, see:

• [references/agent-deployment-guide.md](references/agent-deployment-guide.md)

---

Cross-Skill Integration

| Need | Delegate to | Reason | |---|---|---| | custom object / field creation | [sf-metadata](../sf-metadata/SKILL.md) | define metadata before deploy | | Apex compile / review / fixes | [sf-apex](../sf-apex/SKILL.md) | code authoring and repair | | Flow creation / repair | [sf-flow](../sf-flow/SKILL.md) | Flow authoring and activation guidance | | test data or seed records | [sf-data](../sf-data/SKILL.md) | describe-first data setup and cleanup | | Agent Script build/publish readiness | [sf-ai-agentscript](../sf-ai-agentscript/SKILL.md) | agent-specific correctness |

---

Reference Map

Start here

• [references/orchestration.md](references/orchestration.md)
• [references/deployment-workflows.md](references/deployment-workflows.md)
• [references/deployment-report-template.md](references/deployment-report-template.md)

Specialized deployment safety

• [references/trigger-deployment-safety.md](references/trigger-deployment-safety.md)
• [references/agent-deployment-guide.md](references/agent-deployment-guide.md)
• [references/deploy.sh](references/deploy.sh)

---

Score Guide

| Score | Meaning | |---|---| | 90+ | strong deployment plan and execution guidance | | 75–89 | good deploy guidance with minor review items | | 60–74 | partial coverage of deployment risk | | Target org: Scope: Result: Key findings: Next step:

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Jaganpro](https://github.com/Jaganpro)
- **Source:** [Jaganpro/sf-skills](https://github.com/Jaganpro/sf-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.