Troubleshooting rules

Troubleshooting rulesets

If you cannot perform an action in a repository and want to know why, you can view the active rulesets targeting the branch or tag you're working with. For more information, see "Managing rulesets for a repository."

Depending on which rules are active, you may need to edit your commit history locally before you can push your commits to the remote branch. For example, if a branch requires commits to be signed, you can update your signing settings, then use an interactive rebase on your local branch to rewrite your Git history with signed commits. For more information, see "Available rules for rulesets" and "Using Git rebase on the command line."

If a branch or tag is targeted by rules restricting the metadata of commits, your commits may be rejected if part of the commit's metadata does not match a certain pattern. For example, you might need to add an issue number to the start of your commit message, or change the name of a new branch or tag you're trying to push to the repository. If your commits are rejected, you will see a message telling you the pattern the relevant metadata needs to match. As with signed commits, you may need to perform a rebase to squash the commits or rewrite each commit individually. For more information, see "Available rules for rulesets."

When utilizing push rulesets, a maximum of 1000 reference updates are allowed per push. If your push exceeds this limit, it will be rejected. For more information see "Creating rulesets for a repository".

Troubleshooting ruleset workflows

Ruleset workflows can be configured at the organization level to require workflows to pass before merging pull requests. For more information, see "Creating rulesets for repositories in your organization."

Ruleset workflows for open pull requests

If you create a rule while a pull request is open, the required workflow will not run automatically. To trigger the required workflow, push a new commit, update your branch, or close and re-open the pull request.

Supported ruleset workflow events

Ruleset workflows support using the pull_request, pull_request_target and merge_group events. As a result, you must specify one or more of these events in the on: section of the workflow for the workflow to be run by a ruleset.

Any filters you specify for the supported events are ignored - for example, branches, branches-ignore, paths, types and so on. The workflow is only triggered, and is always triggered, by the default activity types of the supported events.

Event	Default activity types
`pull_request`	`opened`, `synchronize`, `reopened`
`pull_request_target`	`opened`, `synchronize`, `reopened`
`merge_group`	`checks_requested`

For more information, see "Events that trigger workflows."

Ruleset workflows do not run on events triggered by the GITHUB_TOKEN. For more information, see "Automatic token authentication."

Blocking repository creation

A required workflow can block people from creating a repository, since a workflow can't run against a repository that's being initialized. To get around this, the ruleset either needs to have "Evaluate" as the enforcement status, or someone with bypass permissions needs to create the repository and bypass the branch protection.

For more information about enforcement statuses and "Evaluate" mode, see "Creating rulesets for a repository."

For more information about bypass permissions, see "About protected branches."

Branch targets in a ruleset

Verify that your ruleset workflow does not target all branches in the repository. It should only target branches where all changes to the branch are performed by pull requests.

Supported directory

Verify that your workflow file exists in the .github/workflows directory. If you want to run a ruleset workflow on pull_request events in a repository that is not the source repository, you can take any of the following actions:

Add a conditional to the workflow file such as, if: true. For more information, see "Workflow syntax for GitHub Actions."
Disable Actions completely in the source repository. For more information, see "Managing GitHub Actions settings for a repository."
Disable the individual workflow in the source repository. For more information, see "Disabling and enabling a workflow."

Using the `merge_group` trigger

If your repository uses GitHub Actions to perform required checks or if you require workflows via organization rulesets on pull requests in your repository, you need to update the workflows to include the merge_group event as an additional trigger. Otherwise, status checks will not be triggered when you add a pull request to a merge queue. The merge will fail as the required status check will not be reported. The merge_group event is separate from the pull_request and push events.

Source repository permissions

Verify that the source repository permissions are set to "Accessible from repositories in the ORGANIZATION NAME organization."

For more information, see "Managing GitHub Actions settings for a repository."

Source repository privacy settings

Verify that the ruleset workflow file is in a source repository that has the same or less restrictive privacy settings than the repositories you want to run it in. Specifically, a public workflow can run on any repository in your organization, an internal workflow can run on internal and private repositories, and a private workflow can run on private repositories. For more information, see "About workflows."

Who can use this feature?

In this article