Profile Metadata is Overwritten after Deployment

The contents requested in the RetrieveRequest message determine the profile or permission set contents that the Metadata API returns. For example, profiles only include field-level security for fields included in custom objects returned in the same RetrieveRequest as the profiles. Likewise, when a profile is deployed, all of its permissions, custom objects, fields, and page layouts must be manually included; otherwise, they’re removed from the profile .xml file. This behavior can lead to issues where profiles are overwritten when deploying updates.

We recommend that you use permission sets instead of profiles to manage user access and permissions. While permission sets and profiles have the same behavior for retrieve and deploy calls, permission sets are in general more contained, which makes it easier to manage their included settings and permissions. Permission sets allow you to grant users only the permissions they need in a more granular, flexible manner than profiles. You can also bundle permission sets into permission set groups to streamline permission assignment and management.

Use permission sets to manage:

• Apex classes
• Connected app access
• Custom permissions
• Field permissions
• Object permissions
• User permissions (app permissions and system permissions)
• Tab settings
• Visualforce pages

Use profiles to manage:

• Default apps and record types
• IP ranges
• Login hours
• Page layout assignment

Note: You can add profiles to your project's .forceIgnore file so that they’re ignored when pulling changes.

See also:

• Salesforce Help: Guidelines for Creating Permission Sets and Permission Set Groups
• Salesforce Admin Blog: Permissions Updates | Learn MOAR Spring '23
• Salesforce Help: Determine What Metadata Types to Ignore During Development
• Metadata API Developer Guide: PermissionSet
• Metadata API Developer Guide: Profile