Explanation of the issue with External Credential Principal mappings
Salesforce exposes these configurations in different ways depending on whether they are assigned via a Permission Set or via a Profile.
Unfortunately, Salesforce does not include External Credential Principal Access in Profile metadata via the Metadata API, meaning changes assigned through a Profile will not appear in Gearset, and cannot be deployed.
If Principal Access is assigned via a Permission Set, Salesforce exposes it through the Metadata API as:
<externalCredentialPrincipalAccesses>
<externalCredentialName>My_Credential</externalCredentialName>
<principalName>My_Principal</principalName>
<accessLevel>Read</accessLevel>
</externalCredentialPrincipalAccesses>
However, if the Principal Access is assigned through a Profile, Salesforce does not expose any equivalent metadata. No <externalCredentialPrincipalAccesses> node exists in Profile metadata, meaning the change:
will not appear in comparisons
will not deploy through the Metadata API
will not be included in your Git repository
will not be visible or trackable by Gearset
Solution
The only deployable method is to assign Principal Access using Permission Sets:
Move the Principal Access assignment from the Profile into a Permission Set:
Re-run your Gearset deployment or CI job.
What if you must keep the access in a Profile?
If your org requires Principal Access to remain assigned at the Profile level, this configuration cannot be deployed. Instead, manually recreate the External Credential Principal Access in the target org and assign it to the Profile.