When you create a continuous integration (CI) job, you will see a checkbox at the bottom Include user permissions to deploy on the Deployment behavior page:
This checkbox is deselected by default; you can choose to select it.
What are user permissions?
User permissions are a specific type of permissions - they do not include all permissions, such as Custom field permissions (FLS), Layout permissions or Apex class permissions.
In Gearset comparison results, you will see them as Profile: User permission or Permission set: User permission items. For example:
User permission is not a metadata type you can select/deselect in the metadata comparison filter; it is a subcomponent of the Profile or Permission set.
As we describe in our support document on deploying profiles, you can retrieve Profile: User permission items by including the Profile metadata type, plus another metadata type such as Custom object. For user permissions in a permission set, make sure you include the Permission set metadata type.
When you are looking at Gearset comparison results, remember that the results grid will show the API name of each user permission, which may differ from the name in the Salesforce user interface.
Where can I find user permissions in my Salesforce org?
For profiles - if you have the 'Enhanced Profile User Interface' disabled (default)
Changes you make for a profile in the General User Permissions and Administrative Permissions sections will show in Gearset comparison results as Profile: User permission items.
For profiles - if you have the 'Enhanced Profile User Interface' enabled
Changes you make for a profile in the System Permissions and App Permissions sections will show in Gearset comparison results as Profile: User permission items.
For permission sets
For a permission set, changes you make in System Permissions and App Permissions (like those shown above for a profile) will show in Gearset comparison results as Permission set: User permissions.
Should I select the 'Include User Permissions' checkbox for my CI job?
This is down to your personal preference.
As default, the box is deselected, because including them could potentially lead to users losing access, as we warn in the CI job creation form.
Nevertheless, you may be happy to include these changes. Also note that you can use the Difference types to deploy section in the CI job form to prevent any deletions.
I've included user permissions, so why aren't they being deployed?
If you have checked the Include User Permissions box but your Profile: User permission items and/or Permission set: User permissions items (of the correct difference type(s) as specified in your CI job) are not being deployed, check to see whether a Gearset problem analyzer is removing them from the deployment.
Problem analyzer suggested fixes are applied as standard in CI jobs. You can check a job run to see what's been applied:
The screenshot below shows a problem analyzer to watch out for. This applies to both Profile: User permission and Permission set: User permission items.
Can I deploy user permission changes manually?
Yes: if you would like to be able to select individual Profile: User permission items and/or Permission set: User permission items manually, or you find that a problem analyzer is preventing you deploying them via CI, then carry out a manual compare and deploy using Gearset.
Remember that you need the Profile metadata type and another metadata type such as Custom object included in your metadata comparison filter to retrieve Profile: User permission items, and Permission set for Permission set: User permission items.
When carrying out a manual compare and deploy, you can deselect problem analyzer suggested fixes.