How can this article help you troubleshoot CI job issues?
Is your continuous integration (CI) job not deploying an item you expect it to?
Is your CI job showing changes that repeatedly do not get deployed to the target?
If so, we have some questions to help you debug! This article is also designed for you to help you self-serve when troubleshooting CI job issues.
We believe that below guidance will help you with identifying at which stage the problem has occurred and what you can do.
However, if you come into a scenario that we haven't covered in our troubleshooting steps - please reach out to us in the in-app, as we'd like to hear about it!
Steps to troubleshoot your CI job deployment issues
Question 1 - Is the webhook set up for the CI job?
Question 2 - Is the metadata included in the metadata filter?
Question 4 - Has the metadata item made it into the deployment package zip file?
Question 5 - Is the metadata you're deploying referenced in the .forceignore / .gitignore file?
Question 6 - Is it the user permissions that aren't getting deployed to the org?
Other error(s) you may be experiencing in your CI jobs
Question 1 - Is the webhook set up for the CI job?
It's possible that the webhook isn't set up for the CI job.
What's the impact on the CI job?
Lack of webhook set up would impact your CI job in a way that the job will not run. Even if the changes have been merged in the source branch (for example via a PR merged in your Pipelines UI).
How to check wehhook configuration?
On the CI dashboard page, click on the CI job in question or select this option:
, then select Webhook setup...
If a webhook is correctly set up, you'd see a pop up window like this:
Note: If the webhook isn't set up, you will need to configure it.
You may also try re-setting your webhook if it's already configured. We recommend reseting it in scenario where your CI job didn't run at all.
Question 2 - Is the metadata included in the metadata filter?
Sometimes the real cause a CI job isn't deploying something is because that metadata isn't being retrieved in the comparison.
The most common cause of that is because the metadata filter defined in the CI job settings is either:
excluding the metadata type in question (so the metadata you're trying to deploy),
the filter is excluding metadata object(s) that other metadata object(s) depend on
the item you want to deploy belongs to a managed package, and your CI job's filter doesn't have
Include managed packagesoption selected - in which case check this article for more guidance on how to amend your filter: Comparing managed package metadata with Gearset
How to view your metadata filter
On your CI dashboard page, navigate to CI job Edit settings and select Metadata filters tab to see if the named metadata item is included in the metadata filter.
Check below article for more details on metadata filters and how they work:
Custom metadata filters in Compare and deploy and CI jobs
If the filter is missing something you want to deploy (e.g. a specific metadata type isn't added to your filter), you can add the metadata type to the existing filter, save the filter, save your CI job, and once this is done you'd need to re-run the CI job.
Check guidelines on updating filters in automation jobs.
This should deploy to the org the metadata item that falls under the metadata type newly added to your CI job's filter.
For example, below image shows Custom object metadata added to the CI job filter with all its ten sub-components.
How can I view the metadata filter if I'm not the CI job owner?
How can I view the metadata filter if I'm not the CI job owner?
Gearset user who is not the owner of a CI jobs can still preview CI job settings in our app.
For user-owned Pipelines OR standalone CI jobs (jobs not used in Pipelines)
This is only possible if a user has Deployment level access for the target org of the CI job. The CI job owner can assign such access in Orgs Permissions page in our app (more guidance on assigning permission in this article).
Users with Deployment level access to the target org of a CI job will be able to click on View settings button to preview all the configuration for a given job.
For CI jobs used in team-shared / team-owned Pipelines
On the Pipelines & CI jobs page, a Gearset user with a Member status would need the following access to be able to view CI job settings:
Be added to the list of Pipeline users with either
VieworEditaccess.Have either
RunorEdit"CI permission" for a team-shared CI job.Note: If a Member has a
Nonepermission assigned for a team-owned Pipeline, it means this Member is unable to view settings for any of the CI jobs that belong to the Pipeline.
Advanced example on how amending the filter solves a CI issue
Advanced example on how amending the filter solves a CI issue
Here's an example error to illustrate this:
Asset_Automation_Alerts Flow myWaitEvent_myWait_myRule_3_event_2_SA1 (Action) - We can't find an action with the name and action type that you specified.
This is an unhelpful message saying that some action in your Flow references an object not found.
You go to the View Problem Analysis Fixes and select Items that depend on something that isn't on the target and discover that Gearset suggested that
Remove items that reference Asset (CustomObject), which is not available on the target
Asset.Nudge_Reminder_3
Asset.Nudge_Reminder_4
Those are your newly-added email alerts in your Flow. They were excluded because they reference Asset which had been excluded from the CI custom metadata filter.
Editing the custom metadata filter to include Custom Object Asset fixes the CI issue.
Other root causes that may be applicable to your scenario
In SFDX source format repository - is an Apex class / Custom object / Lightning component not showing up in the comparison of your CI job?
In SFDX source format repository - is an Apex class / Custom object / Lightning component not showing up in the comparison of your CI job?
Do you have the corresponding .cls-meta.xml for each .cls file?
Do you have the corresponding .cmp-meta.xml for each .cmp file?
Do you have the corresponding .object-meta.xml for each object in the object directory?
Do you have a .forceignore file that is set to exclude that source file/directory?
That could be the reason Gearset isn't picking up the component.
If we can't retrieve the metadata in your CI job's comparison, it will not be deployed to the target org even if you've successfully merged the PR in your (long-lived) environment branch (if you're using Pipelines workflow for deployments).
We also have a separate documentation covering common problems with viewing metadata in source control, which you may find useful when troubleshooting your CI jobs - particularly in scenarios when the source environment of your CI job is a Git branch.
Question 3 - Has the problem analyzers stripped the metadata item out?
When you run a manual Compare and deploy, after the items to deploy are selected and before the deployment package is created, the problem analyzers kick in.
Problem analyzers are Gearset's intelligent suggestions for your deployment package - their intention is to suggest you to add or remove any components that will help to make your deployment (and its validation) more likely to succeed. You can choose to tick or untick any of these suggestions in order to modify your package.
How do the Problem analyzers work in a CI job?
How do the Problem analyzers work in a CI job?
In a CI job scenario, since it is an automated process, all problem analyzers' suggestions are automatically ticked (which may add or remove components to the final deployment package).
The CI job will then proceed with the deployment. This normally is the most common reason that some items are not deployed in a CI job as you'd expect them to.
If you would like to verify that problem analyzers are the reason that your item is not being deployed via the CI job, you can view the problem analysis results for the CI job run, as described below.
Alternatively, you can run a manual comparison (via Compare and deploy) with the same source and target environments (as set up in your CI job), using the same metadata filter, and clicking through to see the problem analyzers being triggered.
How to amend or disable Problem analyzer used in the CI job
How to amend or disable Problem analyzer used in the CI job
In the Ci job settings there is an option for you to change the problem analyzer used by the CI job. You can also choose to not apply any problem analysis fixes.
To amend this option, on your CI dashboard page select Edit settings... for a CI job in question, then navigate to Advanced tab where you have Assigned analysis template setting.
This allows you to apply one of the two default Problem analysis templates:
- Apply all fixes or
- Don't apply any fixes (this entirely disables Problem Analyzers on your CI job).
And if you have any custom templates created tailored to your own needs (where only a set of specific problem analysis fixes may be enabled), you'd also see the Custom templates section:
You can navigate to the Problem analyzer templates page in our app to create your own custom template if you believe it could help your CI job's validation to succeed.
View problem analysis fixes in CI job history
To see what the problem analyzers are doing under the hood with your CI job, on your CI dashboard navigate to View history for the job in question.
There, you will see a history of your CI job runs with the option to View problem analysis fixes.
Note: The button to preview problem analysis fixes will be greyed out when there are no problem analysis fixes to be shown. This is an expected behaviour.
On below example we're seeing that one of the problem analyzers adds a required master-detail field for an object (WebStoreInventorySource) identified in a deployment package. This is so that the deployment doesn't fail when the field isn't added to the package.
This view shows you which problem analyzers made changes to your job, and which items were affected.
Note: You won't be able to edit anything of the problem analyzers on this page - this section is purely for informational purposes.
If you don't want the CI job to accept the problem analyzers, you can use the feature of the Problem analyzer templates (e.g. to apply a custom analyzer to your CI job), or you can set up your CI job to: Don't apply any fixes to entirely disable problem analyzers.
Question 4 - Has the metadata item made it into the deployment package zip file?
Sometimes it may happen that the metadata item doesn't make it into the deployment package. If it's not in the zip file of the deployment package, then it will not be deployed.
Please, check if the deployment package zip contains the metadata you expected to be deployed. Once you download the zip file, in your file explorer, unzip your zip package and open the metadata with your text editor (for example, you can use VS Code).
If you have any questions about this process, please don't hesitate to ask us in the in-app chat!
Question 5 - Is the metadata you're deploying referenced in the .forceignore / .gitignore file?
When the source of your CI job is a Git branch (e.g. a long-lived environment branch if you're using Pipelines feature), it's possible that the metadata you were expecting to be deployed is referenced in the .forceignore file within your Git repository.
Removing that metadata from the .forceignore file will allow the CI job to deploy that metadata component to the target org on the next CI job run.
Read more about the structure of the .forceignore / .gitignore file
Read more about the structure of the .forceignore / .gitignore file
The .forceignore file structure mimics the .gitignore structure.
Each line in a .forceignore file specifies a pattern that corresponds to one or more files. The files represent metadata components - these can be any files you want to exclude from the deployment.
For more information about the structure of the .forceignore file, you can refer to Salesforce's documentation.
Also, you can refer to Git documentation to read about .gitignore.
Question 6 - Is it the user permissions that aren't getting deployed to the org?
When you create a new CI job, on the Deployment behavior page you can decide whether to include user permissions in the CI deployment (this also includes system permissions and app permissions).
If this setting is disabled, your CI job is configured to not deploy these permissions - even if they've been merged into the source branch of the CI job, or when you have added new or changed user/system/app permissions into a Pull Request and merged the PR into the environment branch (source of the CI job).
This is an expected behavior when deploying changes in your Gearset Pipeline, and not having above option ticked in your CI job settings.
Read more about this functionality in:
What does the checkbox 'Include User Permissions' mean in a CI job?
What's the workaround?
Because this setting cannot be changed after your CI job has been created (whether you've decided to enable or disable it at the CI job creation), the workaround for now is to use manual Compare and deploy and deploy all the permissions directly to the org.
What to do if you just want to deploy the (missing) components to the target environment of your CI job
The quickest way to do this is to use the manual deployment process (by which we mean Compare and deploy) to deploy the items that have not been deployed in the CI job.
Gearset will allow you to unselect the problem analyzer(s) on the dedicated problem analyzers page - which usually gets displayed on the pre-deployment summary page after you've selected your items for deployment and clicked on Next.
Note: Skipping our suggested problem analyzers may result in a validation failure or a deployment error.
After all, the purpose of the problem analyzer(s) is to increase the chances of your successful validation/deployment in the first place.
If a validation or deployment errors happen, you'll need to address the Salesforce errors in order to deploy successfully.
Our dedicated Salesforce validation errors page may help you tackle some of the most commonly seen errors that we've documented.
And if you don't want to deploy the specific changes to the target of the CI job
You can also choose to not deploy specific items into the target.
To remove an item from being included in future CI job runs, you'd need to edit the metadata filter in the CI job setting to exclude those components from showing up in the deployment package the future CI job runs.
Other error(s) you may be experiencing in your CI jobs
It may happen that sometimes you observe an error on your CI job when viewing that job's activities on the CI dashboard page.
Does the error look like this: "An unknown error occurred during problem analysis"?
Does the error look like this: "An unknown error occurred during problem analysis"?
An example of how the error may be displayed on the CI dashboard when your hover your mouse over affected CI job:
How to resolve this issue?
Are you promoting a PR via a CI job within your Pipeline set up?
And is the error happening on that specific PR?
If the answer to the above is yes, please get in touch with our support team via in-app chat. We'll be able to check the logs for the (child) CI job run specific to that PR promotion.
It will help us troubleshoot if you provide us with your CI job ID, which you can find on your CI dashboard:
Possible root cause(s)
From previous use cases we've investigated, this issue may be related to our problem analyzers detecting multiple (or duplicate) metadata components within a specific metadata component in your feature or promotion branch.
We advise to check if the metadata components of which changes you're promoting via PR may have been amended in the target org of the CI job.
It's possible that problem analyzers are detecting an issue due to differences between the metadata components found in the long-lived environment branch (CI source) and the target org (CI target).
Does the error look like this: "An unknown error occurred while logging in. Please try re-authorizing the org, or contact support if you need assistance with this issue."?
Click on the black arrow above: 
to find out how to resolve this issue.
Does the error look like this: "An unknown error occurred while logging in. Please try re-authorizing the org, or contact support if you need assistance with this issue."?
Click on the black arrow above: to find out how to resolve this issue.
An example of how the error may be displayed on the CI dashboard when you hover your mouse over affected CI job:
How to resolve this issue?
Usually, this error indicates a problem with Gearset accessing the access token for the org that is set as the target of the CI job.
For example, the access token may have expired and therefore we are unable to access the org (which wouldn't allow you to run the CI job deployment to that org).
Re-authorizing that org's connection within our app should help you resolve this issue.
You can follow the steps from below article if you need more guidance on how to re-authorize the org connection:
Common authentication and comparison errors
If this doesn't help you resolve the issue, please get in touch with us in the in-app chat.
Note: If you're not the owner of the affected CI job, the re-authorization would need to be done by a team member (on your Gearset team) who owns this CI job connection.
In other words, the re-auth need to be done on the CI job owner's Gearset account.