This document looks to provide guidance around which metadata types to include when setting up Gearset Pipelines for the first time. Ultimately we'd like your pipeline to be as successful, high functioning and low maintenance as possible. That's what this guide hopes to ensure.
Generally speaking, when setting up a git repository for the first time, the advice is to only include metadata types that you're likely to touch. However, even for an experienced developer, it can be really difficult to know up front which types you do and don't touch as a team. Salesforce metadata is inherently complex and heavily interconnected, so there could be dependencies between different types that you're understandably not aware of.
Our advice
What to include
The right starting point depends on how well you know which metadata types your team works with.
Start small when you're confident about your metadata
If you have high confidence about the types of metadata your team regularly creates and changes, we recommend starting with a smaller subset of metadata types.
The Default comparison (63) filter is a good starting point. Review the types it includes and adjust the filter based on what your team regularly works with, adding or removing types as you see fit.
Benefits of this approach: Your repository stays focused on the metadata you actually work with, avoiding unnecessary files and ensuring that the metadata in your repository represents the source of truth for your changes. A smaller repository also means less metadata for your Pipeline to process, which can improve its efficiency.
Potential trade-offs: This approach requires you to have a good understanding of your team's metadata usage. If you inadvertently exclude a metadata type that is needed by your team, you may encounter missing metadata or dependencies when using your Pipeline. While it is possible to add missing metadata types later (see our documentation), depending on your Pipeline complexity and throughput, this can be a cumbersome process, so it's worth taking care when making your initial selection.
Start broad when you're unsure about your metadata
If you don't have a good understanding of the types of metadata your team regularly creates and changes, we recommend taking a more all-encompassing approach.
Salesforce metadata is complex and highly interconnected, so it can be understandably difficult to predict every type that might be needed by your team or as a dependency of another metadata type. In this situation, including more metadata types gives you a safer starting point and reduces the risk of discovering later that something your team needs wasn't included.
Benefits of this approach: Including a broader range of metadata types reduces the risk of missing something your team needs, improving the likelihood that your Pipeline works as expected from the outset. It also reduces the need to maintain your filter by adding missing metadata types later, which can be a time-consuming process. This gives you a more comprehensive starting point without requiring you to have detailed knowledge of your team's metadata usage.
Potential trade-offs: Your repository may contain metadata that your team never actually modifies, resulting in additional files that aren't relevant to your development work. As your repository grows, its performance can be impacted, which can in turn affect the performance of your Pipeline. While this is generally a worthwhile trade-off for the additional confidence that the metadata your team needs is available, it is worth considering if your org is particularly large or complex.
Whichever approach you take, there are a few metadata types that we recommend excluding in most pipeline setups. See What to exclude below.
What to exclude
As with anything, there are a few key exceptions that we'd advise against including as they might introduce problems down the line. As follows:
Installed package - You're safe to include all managed package metadata, but this metadata type is only really needed if you're specifically looking to update the version of managed packages via the Pipeline, and only applies to 1GPs (first-generation packages), 2GP packages aren't managed this way. This metadata type has been known to introduce problems if your package versions aren't perfectly in sync between environments.
Site.com - This is a binary file and the checksum changes frequently, and so a comparison of the same file at two different times often shows as different. Essentially, these files will never be in sync, so are best avoided.
Static Resource - You may not need to exclude all of these, but some of them contain 'Binary: Resource data (MD5)' which is constantly changing and Salesforce can automatically opt to include it in any package that they validate.
Types that are frequently customized directly in Production - Here is suggested list of types that often are edited directly in Production, and so these are at risk of being overwritten as part of a pipeline deployment. If you are familiar with doing the same to one of these types, consider removing it:
Report
Dashboard
ListView (A sub-component of Custom object).
Auth. provider
Certificate
CSP trusted site
Named credentials
SAML SSO config
Anything else - There is no "one size fits all" advice for all customers. There may be particular metadata types that you know you don't want tracked, types that you want to manage outside of the pipeline (similar to our Reports and Dashboards example), in which case, you should remove them from the filter.
When you're done
Once you've configured the filter you'd like to use, be sure to select Save your changes as a new filter. Give your new filter a recognizable name, check Share filter with team and click Save filter. You'll now have access to this saved filter, for use both when initially seeding your repository and configuring your automated jobs. And your team will have access to it for their initial comparisons.
Additional questions
Should we source control ALL metadata types, including those exclusion examples?
If your goal is to simply backup all metadata from an org, then you could consider doing absolutely everything. But in this document, we're specifically talking about configuring your repository/filter to work with Gearset Pipelines. Making some considered exclusions is perfectly fine and recommended.
Do I need to include managed packages to get a Profile’s permissions in full?
Yes, if your Profiles reference managed-package objects or fields. Salesforce retrieves Permission Sets in full regardless of the metadata filter, but Profiles are different. A Profile’s object and field permissions are only retrieved when the related metadata is included. If a managed package namespace is set to None, those permissions won’t be retrieved or compared, which can cause them to disappear from CI jobs and deployments. To avoid this, set Include managed packages to include the namespaces your Profiles reference.
If I want to include other managed package metadata, do I need to do anything?
Yes, it's very common for users to want to include custom objects/fields that relate or are edited as part of managed packages. On the right hand side, be sure to set Include managed packages to All. Or you can set it to Choose and individually select the packages to include.
