Agent-Skills.md

Agent Skills: sf-deploy: Comprehensive Salesforce DevOps Automation

>

UncategorizedID: Jaganpro/sf-skills/sf-deploy

Repository

Jaganpro/sf-skills
JaganproLicense: MIT
6514

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Jaganpro/sf-skills/tree/HEAD/skills/sf-deploy

Skill Files

Browse the full folder contents for sf-deploy.

Download Skill

Loading file tree…

skills/sf-deploy/SKILL.md

Skill Metadata

Name
sf-deploy
Description
>

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

| Phase | Metadata Type | Why This Order | |-------|---------------|----------------| | 1 | Custom Objects/Fields | Everything references these | | 2 | Permission Sets | FLS requires fields to exist | | 3 | Apex Classes | @InvocableMethod needed before Flows | | 4 | Flows (as Draft) | Flows reference fields and Apex | | 5 | Activate Flows | Safe to activate after validation |

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)

Note: Legacy sfdx (v1) is fully retired. Use sf (v2) exclusively.

⚠️ Source tracking requirement (Dec 2025+): sf project deploy start and sf project retrieve start now REQUIRE --source-dir, --metadata, or --manifest on non-source-tracking orgs (production, full sandboxes). Without a scope flag, the command fails.

⚠️ sf org open --url-only: URLs generated with --url-only are single-use and expire after 60 seconds.

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 (--source-dir required on non-source-tracking orgs since Dec 2025)
sf project deploy start --source-dir force-app --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

| 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

  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 via Code Analyzer v5
  4. Dry-run deployment
  5. Run tests + coverage check
  6. Deploy if validation passes
  7. Notify

Static Analysis: Code Analyzer v5

sf code-analyzer (v5) replaced the retired sf scanner (Aug 2025). It bundles ESLint, PMD, RetireJS, and Salesforce-specific rules.

# Install plugin (one-time)
sf plugins install @salesforce/plugin-code-analyzer

# Run scan on source directory
sf code-analyzer run --workspace force-app --output-format csv --output-file scan-results.csv

# Run with specific rule categories
sf code-analyzer run --workspace force-app --rule-selector "Category:Security,Best Practices"

# List available rules
sf code-analyzer rules --output-format csv

# Generate config file for customization
sf code-analyzer config --output-file code-analyzer.yaml

Migration from sf scanner: v5 uses --workspace (not --target), --output-format (not --format), --output-file (not --outfile), and --rule-selector (not --engine/--category).

See references/deployment-workflows.md for full pipeline 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:

| Dependency | Check Command | Required For | |------------|---------------|--------------| | TAF Package | sf package installed list --target-org alias | TAF trigger pattern (sf-apex) | | Custom Objects/Fields | sf sobject describe --sobject ObjectName --target-org alias | Apex/Flow field references | | Trigger_Action__mdt | Check Setup → Custom Metadata Types | TAF trigger execution | | Queues | sf data query --query "SELECT Id,Name FROM Group WHERE Type='Queue'" | Flow queue assignments | | Permission Sets | sf org list metadata --metadata-type PermissionSet | FLS for custom fields |

Common Cross-Skill Issues:

| Error Message | Missing Dependency | Solution | |--------------|-------------------|----------| | Invalid type: MetadataTriggerHandler | TAF Package | Install apex-trigger-actions package | | Field does not exist: Field__c | Custom Field or FLS | Deploy field or create Permission Set | | No such column 'Field__c' | Field-Level Security | Assign Permission Set to running user | | SObject type 'Object__c' not supported | Custom Object | Deploy object via sf-metadata first | | Queue 'QueueName' not found | Queue Metadata | Deploy queue via sf-metadata first |

sf-ai-agentscript Integration (Agent DevOps)

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

Agent Metadata Types

| Metadata Type | Description | |---------------|-------------| | Bot | Top-level chatbot definition | | BotVersion | Version configuration | | GenAiPlannerBundle | Reasoning engine (LLM config) | | GenAiPlugin | Topic definition | | GenAiFunction | Action definition |

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

| Command | Description | |---------|-------------| | sf agent publish authoring-bundle --api-name X --json | Publish authoring bundle | | sf agent publish authoring-bundle --api-name X --skip-retrieve --json | Publish without retrieving metadata (CI/CD) | | sf agent activate --api-name X | Activate published agent (no --json support) | | sf agent deactivate --api-name X | Deactivate agent for changes (no --json support) | | sf agent preview --api-name X | Preview agent behavior (interactive — no --json) | | sf agent preview --authoring-bundle <path> | Preview from local authoring bundle (interactive — no --json) | | sf agent validate authoring-bundle --api-name X --json | Validate Agent Script syntax | | sf org open agent --api-name X | Open in Agentforce Builder | | sf org open authoring-bundle | Open Agentforce Studio list view (v2.121.7+) | | sf agent generate authoring-bundle --api-name X --target-org <alias> --json | Generate authoring bundle scaffolding | | sf agent generate template --agent-file <path> --agent-version <ver> | Generate BotTemplate for ISV packaging (AppExchange) | | sf project retrieve start --metadata Agent:X | Retrieve agent + components | | sf project deploy start --metadata Agent:X | Deploy agent metadata |

Package Management (2GP)

| Command | Description | |---------|-------------| | sf package convert --package <1GP-id> | Convert 1GP to 2GP package (GA, v2.92.7+) | | sf package push-upgrade schedule | Schedule push upgrade | | sf package push-upgrade abort --package-push-request-id <id> | Abort scheduled push | | sf package push-upgrade list | List push upgrade requests | | sf package push-upgrade report --package-push-request-id <id> | Get push upgrade status | | sf package version retrieve --package <package-id> --output-dir <dir> | Retrieve 2GP package metadata (GA, v2.111.7+) | | sf package version create --generate-pkg-zip --package <name> | Generate installable .zip alongside version (v2.123.1+) |

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:

| Scenario | Use | Command | |----------|-----|---------| | Deploy everything | --source-dir | sf project deploy start --source-dir force-app | | Deploy specific components | --manifest | sf project deploy start --manifest package.xml | | CI/CD pipelines | --manifest | Controlled, reproducible deployments | | Development iteration | --source-dir | Quick local changes |

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