You may run into these errors when performing one of these actions in Gearset:
Committing changes to a branch (most commonly Main) using Compare and deploy
Promoting changes between environments in your Gearset Pipeline
Validating a pull request (PR) in your Gearset Pipeline, where the PR reports the error in the
Metadata validationtabResolving merge conflicts on a PR your Gearset Pipeline
Committing changes to your branch that are built with Gearset Agent (in the same way as you would do via Compare and deploy)
Generic error message displayed in Gearset
Currently, Gearset shows a generic error in the app, which reads:
There has been a problem deploying your changes. The error message returned was:
Push failed: couldn't push branch, likely because the repo has changed - try refreshing the comparison
This is how it appears for deployments attempted in Compare and deploy:
In a Gearset Pipeline, it appears on the PR validation as shown below:
Git-related errors surfaced in our logs
This section lists the errors, typically Git-related, that our logs have shown as the underlying cause(s) of this issue.
Note: These are specifically GitHub error codes, so they only appear for GitHub repositories (GitHub.com and GitHub Enterprise). Azure DevOps, GitLab and Bitbucket can reject pushes (commits) for the same reasons while returning their own error messages - so different wording or text formatting may apply for other Version Control Systems (VCSs).
Error 1 - "GH013: Repository rule violations found for refs/heads/main - Changes must be made through a pull request"
This is a common error if you're trying to make a commit (deployment) from a source environment (e.g. a Salesforce org) to the Main/Master branch of your organisation's Git repository. In our logs, this reports as:
error: GH013: Repository rule violations found for refs/heads/main.
remote: - Changes must be made through a pull request
Root cause
The Main/Master branch of the repository has a rule that requires changes to go through a pull request, so every direct push to Main/Master gets refused.
These rules are created and managed by your repository or organisation admins in GitHub - through rulesets or branch protection rules. Gearset doesn’t create or control the rules, nor can we override them.
If your team uses GitHub, see this documentation on managing a branch protection rule and managing rulesets for a repository.
Until the commit meets the rule, or the rule is changed, GitHub will keep rejecting the push (commit), no matter how many times you retry the deployment or refresh the comparison in our app.
How to fix
Commit to a new feature branch created from Main, then open a PR into Main.
If a one-off direct commit to Main is genuinely needed, for example to seed a new repository for a new Pipeline, ask your repository admin to temporarily disable the rule or add the Gearset-connected GitHub user to the ruleset’s bypass list.
Error 2 - "GH013: Repository rule violations found for refs/heads/<feature_branch_name> - Changes must be made through a pull request"
This is the same rule as for the error 1, but here it applies to a feature branch. For example, when you commit to a new feature branch created from Main in your Gearset Pipeline - in our logs, the error reports as:
error: GH013: Repository rule violations found for refs/heads/<feature_branch_name>.
remote: - Changes must be made through a pull request
Root cause
The pull-request-only ruleset targets all branches in the repository (for example a target of All branches or the pattern *), not just your environment branches in the pipeline.
In a Gearset Pipeline, you first commit pushes changes directly to a feature branch. Pull requests are used only when promoting into environment branches. A ruleset that requires PRs on every branch will blocks that first step, and prevent you from making a commit.
How to fix
Ask your repository admin to narrow the ruleset's target branches to the environment branches used by your Pipeline (for example Main, Pre-Prod, UAT, QA etc).
Alternatively, add the Gearset-connected GitHub user to the ruleset's bypass list.
Tip: In GitHub, go to Settings > Rules > Rule insights in your repository to see which ruleset blocked a push.
Error 3 - "GH013: Repository rule violations found for refs/heads/<branch> - Commits must have verified signatures"
This affects commits, promotions, PR validations and merge conflict resolution in Gearset Pipelines. In our logs, it reports as:
error: GH013: Repository rule violations found for refs/heads/<branch>.
remote: - Commits must have verified signatures.
remote: Found 1 violation: <commit SHA>
Root causes
The repository requires signed commits, and at least one commit in the push is unsigned or can't be verified by GitHub. We've seen this happen when:
Commit signing isn't set up in Gearset for the user making the commit.
The signing key isn't added to the GitHub account, or its email doesn't match a verified email on that account.
The account Gearset commits as has lost its bypass permission for the signing rule, even temporarily.
Older unsigned commits are already in the target branch. Gearset brings these into the promotion branch when it merges, so the push fails even though your own commit is signed.
How to fix
Set up commit signing in Gearset and add the key to the matching GitHub account.
Check the commit SHAs listed in the error to see which commits aren't verified and who made them.
If unsigned commits are already in an environment branch, ask your repository admin to temporarily relax the rule (or grant a bypass) so they can be promoted through, then turn the rule back on. Avoid rewriting the history of environment branches, as this can disrupt open feature branches and PRs.
Tip: For reference, check GitHub's documentation about commit signature verification.
Error 4 - "GH013: Repository rule violations found for refs/heads/<branch> - Push cannot contain secrets"
This often happens on an initial commit of a whole org, or when committing Custom Labels or Custom Metadata. In our logs, it reports as:
error: GH013: Repository rule violations found for refs/heads/<branch>.
remote: - GITHUB PUSH PROTECTION
remote: - Push cannot contain secrets
remote: —— <secret type, e.g. Google API Key> —— path: <file>:<line>
Root cause
GitHub secret scanning found a value in the metadata you're committing that looks like a credential, such as an API key, access token or signed URL. Custom Labels and Custom Metadata records are the most common sources.
How to fix
Use the file path and line number in the error to find the flagged component, then deselect it from your commit.
If the value is a false positive or an already-retired secret, use the unblock link in the full error (or ask your repository admin) to allow it.
If it's a real, active secret, treat it as exposed and rotate it. Longer term, move it out of version-controlled metadata, for example into a Named Credential or protected Custom Metadata.
Tip: Check GitHub's documentation on resolving a blocked push.
Error 5 - "GH013: Repository rule violations found for refs/heads/<branch> - Commit message must match a given regex pattern"
This can start suddenly after your team adds a commit message rule, even though the same commits worked before. In our logs, it reports as:
error: GH013: Repository rule violations found for refs/heads/<branch>.
remote: - Commit message must match a given regex pattern: <pattern>
Root cause
Your repository has a rule requiring commit messages in a specific format, for example starting with a ticket reference such as [SF-1234]. The message on the commit Gearset tried to push doesn’t match it.
How to fix
Check the pattern shown in the error and write your commit message in that format.
Ask your repository admin whether the pattern should also allow the automatic commit messages Gearset uses for merges and promotions.
Tip: Check GitHub's documentation about available rules for rulesets.
Error 6 - "GH013: Repository rule violations found for refs/heads/<branch> - Required workflow is not satisfied"
This usually comes from organisation-wide rules, for example security or compliance scans. In our logs, it reports as:
error: GH013: Repository rule violations found for refs/heads/<branch>.
remote: - Required workflow '<workflow name>' is not satisfied
Root cause
An organisation ruleset requires one or more GitHub Actions workflows to run and pass before the branch can be updated. These workflows didn't run, or didn't pass, for the branch you're committing to.
How to fix
Ask your repository admin which workflows are required and make sure they run and pass for the branch.
Alternatively, ask them to scope the rule so it doesn’t apply to the branches you commit to via Gearset.
Tip: Check GitHub's documentation about available rules for rulesets.
Other GitHub-related causes (not GH013)
The errors listed in this section are not associated with GitHub's GH013 rule violations, but Gearset currently shows either the same or a slightly different generic message in the app's UI for each of them.
Error 7 - "refusing to allow an OAuth App to create or update workflow <.github/workflows/<file>.yml> without workflow scope"
You may run into this error when committing, promoting or validating a PR in your Gearset Pipeline, if the changes include a GitHub Actions workflow file (any file under .github/workflows/).
This usually happens when someone edits a workflow file directly in GitHub, and that change is later picked up by a feature or promotion branch that Gearset pushes.
Depending on where it happens, Gearset shows either the generic Push failed: couldn’t push branch… message, or a more general error on the validation CI job associated with your PR (see example below).
In our logs, this reports as:
! [remote rejected] <branch> (refusing to allow an OAuth App to create or update workflow .github/workflows/<file>.yml without workflow scope)
Root cause
Your commit or promotion includes changes to a GitHub Actions workflow file under .github/workflows/. GitHub only allows apps with the workflow permission to change these files. This often happens when a promotion branch picks up workflow changes that were made directly in GitHub.
How to fix
Make changes to workflow files directly in GitHub, and keep them out of your Gearset commits and promotions.
If workflow changes need to flow through your Pipeline branches, ask your GitHub admin to grant the workflow permission to the GitHub account Gearset uses for promotions. In team-shared Pipelines, this is usually a GutHub service account - check if your team users a service account to run promotions in the pipeline.
Tip: For more information, check GitHub's documentation: Scopes for OAuth apps.
Error 8 - "Resource not accessible by integration" (status: 403)
This usually affects team-shared pipelines, where some actions use the team's shared Git credentials. In our logs, it reports as:
{"message":"Resource not accessible by integration", … "status":"403"}
Root cause
The Git account Gearset uses for this action doesn't have the access it needs to the branch or its protection settings, even if other users in your team can work with the same branch.
How to fix
Check which Git credentials your pipeline uses for this action and confirm that account has write access to the branch.
Review the branch protection and ruleset settings for that branch with your repository admin.
Tip: For more info, check our documentation on which Git credentials are used for which actions in Pipelines.
Error 9 - "<branch> matches more than one"
This can affect any Git provider, including GitHub. It can appear as:
error: src refspec <branch> matches more than one
Root cause
A branch or tag with the same name, or a clashing name, already exists in the repository. For example, Git may be unable to create a branch named SF-123/my-change if a branch called SF-123 already exists.
How to fix
Use a unique name for your new branch.
Alternatively, ask your repository admin to delete or rename the existing branch or tag if it's no longer needed.
Check GitHub status page for incidents
If the error doesn’t point to a specific rule, or the same action succeeds when you try again a few minutes later, the push probably failed during a temporary GitHub incident. To check whether that's the case, follow below steps.
How to approach it
Check GitHub's Status page for ongoing incidents.
Refresh the comparison and try again once the incident is resolved.
Feedback
If you have run into any of the above errors, or into any unknown or undefined error in our app, and are not sure which resolution applies to your use case or scenario - we encourage you to get in touch with our Customer Support via in-app chat.
We'll be happy to dig into the logs to help you understand the underlying cause of the error show in Gearset app.