Profiles are different to many other metadata types on the metadata API. The subcomponents returned by Salesforce for a profile depend on the other metadata types in your metadata filter.

For example, if you select just the Profile metadata type in your custom metadata filter and run a comparison, you'll get only the user permissions of the Profile.

So which metadata types should you include in the custom filter to retrieve each individual part?

We created a Default profiles and permission sets comparison filter for those of you that don't need the details further below. Not sure how to manage your custom metadata filter? See here.

Here is a handy reference table showing you which other metadata types you'll need to include in your filter to get each subcomponent type in your profile:

Since this is under component in the table, select the profile with the FLS changes and using the dropdown arrow, find components.

In my metadata filter I have Profile and Custom object selected. Once you have expanded components you should be able to see all the FLS that you expected to see.

Sometimes, you may run into order-dependency issues when trying to deploy changes to Profiles. Here’s one example for Profile MyCustomerSuccess

When you try to deploy this, Salesforce first removes the Delete (D) and Modify All permission from the Profile in the target org and then immediately throws up a Validation Error: “Manage Cases requires delete permission”.

There are two options for working around this:

Option 1: Do two deployments - one to remove Manage Cases permission first, then a second deployment to remove D and Modify All from Case.

Option 2: Go into the target org and manually remove Manage Cases user permission. Then deploy the object permissions via Gearset.

Since this is under Top level in the table, you can see the Apex class permissions in the comparison table.

In my metadata filter I have Profile and Apex class selected.

If a profile is completely new - it does not exist at all in the target environment for your deployment - it will always appear as a single item in your comparison results with a change type of New.

In this case, you'll need to deploy the entire profile object. You can't select a subcomponent to deploy as the profile framework does not yet exist in the target environment.

If you want to work around this limitation on new profiles, you can try creating the profile manually in your target environment as a blank placeholder. When you refresh your comparison, Gearset will then be able to deploy any changed subcomponents.

Please note: You will still need to include the relevant metadata types in your filter to ensure each component of the new profile is retrieved).

When deploying an entirely new profile, you will also run into this Salesforce metadata API behavior here. This will cause some false custom object (and others) permissions to be set to true on the target org after deployment based on the Standard User profile in your target org.

To address this behavior, it is recommended to deploy an entirely new profile in two steps: First the new profile itself, then in a second deployment all the custom permissions that were missed due to the above behavior.

Gearset also makes it possible and easy to deploy the permissions of an item across multiple profiles and/or permission sets. The following 6 groupings of metadata types allow you to deploy the permission of not just one profile at a time, but of multiple profiles in one go.