Back to Details

deploying-metadata

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

deploying-metadata: Comprehensive Salesforce DevOps Automation

deploying-metadata：全面的Salesforce DevOps自动化

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.
当用户需要部署编排时使用此技能：预演验证、定向或基于清单的部署、CI/CD工作流建议、临时环境（scratch-org）管理、故障排查，或Salesforce元数据的安全发布排序。

When This Skill Owns the Task

此技能负责的任务场景

Use 
deploying-metadata
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 code → generating-apex
  • authoring LWC components → generating-lwc-components
  • creating custom objects or fields → generating-custom-object, generating-custom-field
  • building Flows → generating-flow
  • doing org data operations → handling-sf-data
  • authoring or testing Agentforce agents → developing-agentforce
当工作涉及以下内容时，使用
deploying-metadata
：
  • sf project deploy start
    、
    quick
    、
    report
    或检索工作流
  • 跨对象、权限集、Apex和Flows的发布排序
  • CI/CD关卡、测试级别选择或部署报告
  • 排查部署失败问题和依赖项排序
当用户从事以下工作时，请转交至其他技能：
  • 编写Apex代码 → generating-apex
  • 编写LWC组件 → generating-lwc-components
  • 创建自定义对象或字段 → generating-custom-object、generating-custom-field
  • 构建Flows → generating-flow
  • 执行组织数据操作 → handling-sf-data
  • 编写或测试Agentforce代理 → developing-agentforce

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 
    handling-sf-data
     after metadata is validated or deployed.
  • 仅使用**
    sf
    CLI v2**。
  • 在非源码跟踪的组织中，部署/检索命令需要明确的范围，例如
    --source-dir
    、
    --metadata
    或
    --manifest
    。
  • 实际部署前优先执行**
    --dry-run
    预演**。
  • 对于Flows，安全部署并仅在验证后激活。
  • 元数据验证或部署完成后，测试数据创建指导请转交至**
    handling-sf-data
    **。

Default deployment order

默认部署顺序

PhaseMetadata
1Custom objects / fields
2Permission sets
3Apex
4Flows as Draft
5Flow activation / post-verify
This ordering prevents many dependency and FLS failures.
阶段元数据
1自定义对象/字段
2权限集
3Apex
4草稿状态的Flows
5Flow激活/验证后操作
此顺序可避免许多依赖项和FLS（字段级安全）失败问题。

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:
bash
sf --version
sf org list
sf org display --target-org <alias> --json
test -f sfdx-project.json
询问或推断：
  • 目标组织别名和环境类型
  • 部署范围：source-dir、元数据列表或清单
  • 本次操作是仅验证、部署、快速部署、检索还是CI/CD指导
  • 要求的测试级别和回滚预期
  • 是否涉及特殊元数据类型（Flow、权限集、代理、包）
预检查命令：
bash
sf --version
sf org list
sf org display --target-org <alias> --json
test -f sfdx-project.json

Recommended Workflow

推荐工作流

1. Preflight

1. 预检查

Confirm auth, repo shape, package directories, and target scope.
确认身份验证、仓库结构、包目录和目标范围。

2. Validate first

2. 先执行验证

bash
sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json
Use manifest- or metadata-scoped validation when the change set is targeted.
bash
sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json
当变更集为定向时，使用基于清单或元数据范围的验证。

3. If validation succeeds, offer the next safe workflow

3. 验证成功后，提供下一步安全工作流

After a successful validation, guide the user to the correct next action:
  1. deploy now
  2. assign permission sets
  3. create test data via handling-sf-data
  4. run tests / smoke checks
  5. orchestrate multiple post-deploy steps in order
验证成功后，引导用户执行正确的下一步操作：
  1. 立即部署
  2. 分配权限集
  3. 通过handling-sf-data创建测试数据
  4. 运行测试/冒烟检查
  5. 按顺序编排多个部署后步骤

4. Deploy the smallest correct scope

4. 部署最小且正确的范围

bash
undefined
bash
undefined

source-dir deploy

基于source-dir的部署

sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json

manifest deploy

基于清单的部署

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

manifest deploy with Spring '26 relevant-test selection

适用于Spring '26的相关测试选择的清单部署

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

quick deploy after successful validation

验证成功后的快速部署

sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json
undefined
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json
undefined

5. Verify

5. 验证部署结果

bash
sf project deploy report --job-id <job-id> --target-org <alias> --json
Then verify tests, Flow state, permission assignments, and smoke-test behavior.
bash
sf project deploy report --job-id <job-id> --target-org <alias> --json
然后验证测试结果、Flow状态、权限分配和冒烟测试行为。

6. Report clearly

6. 清晰报告

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 / symptomLikely causeDefault fix direction
FIELD_CUSTOM_VALIDATION_EXCEPTION
validation rule or bad test dataadjust data or rule timing
INVALID_CROSS_REFERENCE_KEY
missing dependencyinclude referenced metadata first
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY
trigger / Flow / validation side effectinspect automation stack and failing logic
tests fail during deploybroken code or fragile testsrun targeted tests, fix root cause, revalidate
field/object not found in permsetwrong orderdeploy objects/fields before permission sets
Flow invalid / version conflictdependency or activation problemdeploy as Draft, verify, then activate
Full workflows: references/orchestration.md, references/trigger-deployment-safety.md
错误/症状可能原因默认修复方向
FIELD_CUSTOM_VALIDATION_EXCEPTION
验证规则或测试数据错误调整数据或规则执行时机
INVALID_CROSS_REFERENCE_KEY
缺少依赖项先包含被引用的元数据
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY
触发器/Flow/验证的副作用检查自动化栈和失败逻辑
部署期间测试失败代码损坏或测试不稳定运行定向测试，修复根本原因，重新验证
权限集中未找到字段/对象部署顺序错误先部署对象/字段，再部署权限集
Flow无效/版本冲突依赖项或激活问题以草稿状态部署，验证后再激活
完整工作流：references/orchestration.md、references/trigger-deployment-safety.md

CI/CD Guidance

CI/CD指导

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)
    — see generating-apex for authoring guidance.
Static analysis now uses Code Analyzer v5 (
sf code-analyzer
), not retired 
sf scanner
.
Deep reference: references/deployment-workflows.md
默认流水线结构：
  1. 身份验证
  2. 验证仓库/组织状态
  3. 静态分析
  4. 预演部署
  5. 测试+覆盖率关卡
  6. 部署
  7. 验证+通知
  • 当组织策略和发布风险允许时，对于Apex密集型部署，可考虑使用
    --test-level RunRelevantTests
    。
  • 搭配现代Apex测试注解，如
    @IsTest(testFor=...)
    和
    @IsTest(isCritical=true)
    ——编写指导请参见generating-apex。
静态分析现在使用Code Analyzer v5（
sf code-analyzer
），而非已停用的
sf scanner
。
深度参考：references/deployment-workflows.md

Agentforce Deployment Note

Agentforce部署说明

Use this skill to orchestrate deployment/publish sequencing around agents, but use the agent-specific skill for authoring decisions:
  • developing-agentforce for 
    .agent
    authoring, Agent Builder, Prompt Builder, and metadata config
For full agent DevOps details, including 
Agent:
pseudo metadata, publish/activate, and sync-between-orgs, see:
  • references/agent-deployment-guide.md
使用此技能编排代理相关的部署/发布顺序，但代理编写决策请使用专门的技能：
  • developing-agentforce用于
    .agent
    编写、Agent Builder、Prompt Builder和元数据配置
有关代理DevOps的完整细节，包括
Agent:
伪元数据、发布/激活以及跨组织同步，请参见：
  • references/agent-deployment-guide.md

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
custom object creationgenerating-custom-objectdefine objects before deploy
custom field creationgenerating-custom-fielddefine fields before deploy
Apex authoring / fixesgenerating-apexcode authoring and repair
Flow creation / repairgenerating-flowFlow authoring and activation guidance
test data or seed recordshandling-sf-datadescribe-first data setup and cleanup
Agent authoring and publish readinessdeveloping-agentforceagent-specific correctness
需求转交至原因
自定义对象创建generating-custom-object部署前定义对象
自定义字段创建generating-custom-field部署前定义字段
Apex编写/修复generating-apex代码编写与修复
Flow创建/修复generating-flowFlow编写与激活指导
测试数据或种子记录handling-sf-data先描述再进行数据设置与清理
代理编写与发布就绪检查developing-agentforce代理专属的正确性检查

Reference Map

参考地图

Start here

入门参考

  • references/orchestration.md
  • references/deployment-workflows.md
  • references/deployment-report-template.md
  • references/orchestration.md
  • references/deployment-workflows.md
  • references/deployment-report-template.md

Specialized deployment safety

专项部署安全

  • references/trigger-deployment-safety.md
  • references/agent-deployment-guide.md
  • references/deploy.sh
  • references/trigger-deployment-safety.md
  • references/agent-deployment-guide.md
  • references/deploy.sh

Asset templates

资产模板

  • assets/package.xml — manifest template covering common metadata types
  • assets/destructiveChanges.xml — template for removing metadata from target orgs
  • assets/package.xml — 涵盖常见元数据类型的清单模板
  • assets/destructiveChanges.xml — 用于从目标组织移除元数据的模板

Score Guide

评分指南

ScoreMeaning
90+strong deployment plan and execution guidance
75–89good deploy guidance with minor review items
60–74partial coverage of deployment risk
< 60insufficient confidence; tighten plan before rollout
分数含义
90+完善的部署计划与执行指导
75–89良好的部署指导，存在少量需审查项
60–74部分覆盖部署风险
< 60信心不足；发布前需收紧计划

Completion Format

完成格式

text
Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>
text
Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>