Permission Set Deployment Ordering

Permission Set Deployment Ordering

Use this skill when deploying permission sets, permission set groups, or profiles and encountering cross-reference errors, silent permission wipeouts, or deployment ordering failures. It covers the full-replace behavior of the Metadata API for permission sets and the correct sequencing rules that prevent data loss in production deployments.

Before Starting

Gather this context before working on anything in this domain:

• Know whether you are deploying permission sets, permission set groups, or both. PSGs require all constituent permission sets to already exist in the target org before the group can land.
• Understand that the Metadata API performs a full-replace on permission sets (API v40+), not a merge. Any permission not in the deployed XML is silently removed from the target org.
• Confirm whether your batch includes a ConnectedApp and a permission set or PSG referencing that ConnectedApp — this combination triggers a known cross-reference error when both land in the same deploy transaction.

Core Concepts

Full-Replace Semantics (API v40+)

Since API version 40.0, deploying a PermissionSet metadata type completely overwrites the existing record in the target org. If you retrieve a permission set, remove three field permissions from the XML, and deploy it — those three permissions are gone in the target. There is no merge; the deployed XML is authoritative.

This behavior means: always retrieve the current state from the target org before building a deployment package. Never deploy a permission set constructed from scratch unless you have confirmed the target org has no existing configuration to preserve.

Referenced Objects Must Exist First

Permission sets that grant access to custom objects, custom fields, Apex classes, or Visualforce pages require those components to already exist in the target org before the permission set deploys. If the deploy batch includes both the custom object and the permission set that grants access to it, order matters: the object must land before the permission set.

In a Metadata API deployment, objects are processed before permission sets by default because the deployment engine uses a built-in ordering. However, in split deployments (object in one deploy, PS in another), ensure the first deploy completes successfully before starting the second.

PSG Constituent Ordering

Permission Set Groups require each constituent Permission Set to already exist in the target org (or be deployed in the same batch before the PSG is evaluated). If a PSG references PS_A and PS_B, both must be present before PSG_1 is processed.

Safe pattern: deploy constituent PSets first (separate deploy or earlier in the batch), then deploy the PSG in a subsequent deploy. Do not rely on implicit ordering within a single batch unless you have verified the Metadata API processes them in the correct order.

ConnectedApp Cross-Reference Bug

A known platform bug causes a cross-reference error when a ConnectedApp and a permission set or PSG that references that ConnectedApp are both included in the same deployment batch. The workaround is to deploy the ConnectedApp in a separate deploy from the permission set that grants access to it.

Common Patterns

Retrieve-Then-Deploy Pattern

When to use: Any time you need to update a permission set without inadvertently removing existing permissions.

How it works:

1. Retrieve the current permission set from the target org: sf project retrieve start --metadata "PermissionSet:My_PS"
2. Make only the needed changes in the local XML.
3. Deploy the modified file: sf project deploy start --metadata "PermissionSet:My_PS"

Why not construct from scratch: A constructed-from-scratch XML only contains the permissions you explicitly added. All permissions already granted in the target org that are not in your XML will be silently removed on deploy.

Sequential Batch Deployment Pattern

When to use: Deploying permission set groups whose constituent sets may not already exist in the target.

How it works:

1. Deploy 1: PermissionSet:PS_A, PermissionSet:PS_B — confirms both land and pass tests.
2. Deploy 2: PermissionSetGroup:PSG_1 — PSG references PS_A and PS_B, which now exist.

Why not a single batch: While the Metadata API often processes PSets before PSGs in a single batch, this is not guaranteed and there is no documented specification. The sequential pattern is explicit and repeatable.

ConnectedApp Isolation Pattern

When to use: Deploying a ConnectedApp and a PermissionSet or PSG that references it.

How it works:

1. Deploy 1: ConnectedApp:My_App
2. Deploy 2: PermissionSet:My_PS (which grants access to My_App)

Why not together: The cross-reference resolution order in the same batch causes a platform error even though both components are present. Separation into sequential deploys resolves it.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner deploying permission sets:

1. Identify all permission sets and PSGs in the deployment package. List their dependencies: which custom objects, fields, Apex classes, or ConnectedApps they reference.
2. Retrieve the current state from the target org for any permission set that already exists there. Use sf project retrieve start --metadata "PermissionSet:<name>" to get the authoritative current XML.
3. Merge your changes into the retrieved XML rather than replacing it. Only modify the specific permissions you intend to add, remove, or change.
4. Check for ConnectedApp references. If any PS or PSG in the batch references a ConnectedApp also in the batch, split into two sequential deploys: ConnectedApp first, then the PS/PSG.
5. Sequence the deployment batches. Deploy constituent PSets before PSGs. Deploy custom objects/fields before the PSets that reference them.
6. Validate deploy first (sf project deploy validate) before running the actual deploy in production. Review any cross-reference errors in the validation output and resolve them.
7. Confirm post-deploy that key permission grants are still intact in the target org. Use sf project retrieve start to pull the deployed PS and diff against expectations.

Review Checklist

Run through these before marking work in this area complete:

• Retrieved current state of all existing permission sets from the target org before building deploy package
• Verified no ConnectedApp and permission set referencing it are in the same deploy batch
• Confirmed all constituent PSets deploy before any PSG that references them
• Confirmed all referenced custom objects, fields, and Apex classes exist in target before PS deploys
• Ran sf project deploy validate and resolved all errors before actual deploy
• Post-deploy verification: retrieved deployed PS and confirmed expected permissions are present

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Silent permission wipeout on full-replace — Deploying a PermissionSet that is missing permissions which exist in the target org silently removes those permissions. There is no warning or error. Always retrieve from the target first and perform a diff before deploying.
2. ConnectedApp cross-reference error in same batch — Including a ConnectedApp and a PermissionSet or PSG referencing it in the same deployment batch causes a CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY or cross-reference error. The fix is always a sequential deploy: ConnectedApp first, permission set second.
3. PSG validation failure when PSets are missing — A Permission Set Group deployed to an org where one of its constituent PSets does not yet exist will fail with a validation error referencing the missing set. PSets must be deployed before PSGs that reference them.

Output Artifacts

Related Skills

• permission-set-architecture — when to design PSets vs PSGs vs Profiles for user access strategy
• change-set-deployment — for change-set-based deployment workflows where metadata ordering is also relevant
• deployment-error-troubleshooting — for diagnosing the specific error messages that arise from PS deployment failures