Legend:

Required = Needed for Gearset deployments to work.

Recommended = Grant to avoid common failures.

Situational / verify = Only some orgs need it; grant if you hit the matching error, and confirm in your own org.

This checklist assumes the deployment user has a standard Salesforce user license. We don’t recommend using a Salesforce Integration user license for the Gearset deployment user. Read more about Salesforce Integration user licenses and why a standard license is a better fit for Gearset.

Permission	Status	Why / what breaks without it
Modify All Data	Required (primary)	Core permission for metadata and data deployments. Without it, comparisons/deployments fail with "Insufficient user permissions – the user must have 'Modify All Data' or 'Modify Metadata Through Metadata API Functions'."
Modify Metadata Through Metadata API Functions	Alternative to Modify All Data	Narrower Metadata API gate. Works only if you also add the correct per‑type permission for every metadata type you deploy. If you’re not sure which type-specific permissions you need, check the error reference table below.
API Enabled	Required	Gearset connects entirely via the API.
Customize Application	Required	Needed for certain metadata types even when `Modify All Data` / `Modify Metadata` are already set. Confirmed to unblock Flow and Lightning (LWC) deployments ("insufficient access rights on entity: FlowRecord / LightningComponentResource") and some app/config metadata. The surfaced error is misleading, it names Modify All Data, but Customize Application is the actual fix. Grant if you deploy Flows, LWC, apps, custom metadata types or custom settings.
View All Data	Recommended	Broad read access; useful for retrieval. Resolves the "Could not retrieve item: 'ApexClass'" deployment issue reported by customers using a granular set.
View Setup and Configuration	Recommended	Reading org setup/config that metadata references.
Author Apex	Recommended	Deploying Apex classes/triggers.
Manage Flow	Recommended	App permission. Required to deploy Flows as standalone items
Manage Profiles and Permission Sets	Recommended	Deploying profiles and permission sets.
Manage Custom Permissions	Recommended	Deploying custom permissions.
View Roles and Role Hierarchy	Recommended	Metadata that references roles.
Create and Customize List Views	Situational	List views (with `Manage Public List Views`).
Create and Set Up Experiences / Manage Experiences	Situational	Experience Cloud metadata.
View Event Log Files	Situational	Only if event log related metadata is in scope.
View Dashboards in Public Folders / View Reports in Public Folders	Situational	Only if deploying dashboards/reports.
Field‑level read/edit on the fields in scope	Situational	`Modify All Data` does not guarantee field‑level visibility for every field. If Gearset can't see/filter a custom field, add field‑level permissions (or deploy a permission set that grants them).
Cloud‑specific permissions (e.g. Financial Services Cloud → View All Fields; View Threat Detection Events; Field Service Lightning)	Situational	Some clouds/objects need extra permissions for retrieval or deployment. If you run these clouds, confirm the specific permissions in your org — there is no universal list.

If your organization follows a least privilege approach, keep in mind that Modify All Data is intentionally broad and effectively supersedes most of the specific permissions in this table. For a narrower setup, use Modify Metadata Through Metadata API Functions together with the specific per-type and field-level permissions your deployments need, rather than defaulting to Modify All Data.

⚑ Why some rows are flagged: In several real cases the fix worked but Salesforce provides no authoritative "type → permission" mapping, so treat flagged items as "grant if you hit the matching error, and verify in your own org." Granting Modify All Data avoids needing most of them.

Error → likely missing permission (quick reference)

Error you see	Most likely cause / fix
Insufficient user permissions – the user must have "Modify All Data" or "Modify Metadata Through Metadata API Functions"	The deploying user lacks the core Metadata API permission. Grant `Modify All Data`. Common right after a sandbox refresh.
insufficient access rights on entity: FlowRecord / LightningComponentResource	Add Customize Application to the deploying user.
Could not retrieve item: 'ApexClass'	Add View All Data (reported fix) / ensure `Author Apex`.
insufficient access rights on cross-reference id: <xxx>	Two possible causes: (a) a referenced setup/config entity the user can't access → often Customize Application; or (b) for Flow deletions, all versions of the Flow must be deleted (not a permission issue). Use a self‑compare (Compare & Deploy the org against itself) to identify the specific failing component.
Gearset can't see / filter a custom field	Add field‑level read for that field, or deploy a permission set granting it. `Modify All Data` alone may not cover field visibility.

Deployment User in Salesforce - Permission checklist

Error → likely missing permission (quick reference)