doc/user/project/repository/push_rules.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Push rules are pre-receive Git hooks you
can enable in a user-friendly interface. Push rules give you more control over what
can and can't be pushed to your repository. While GitLab offers
protected branches, you may need more specific rules, such as:
GitLab uses RE2 syntax for regular expressions in push rules. You can test them at the regex101 regex tester. Each regular expression is limited to 511 characters.
For custom push rules use server hooks.
[!note] Push rules are bypassed during fork synchronization. When you update your fork from its upstream project, changes are applied directly without validation against the fork's push rules.
Push rules work as templates, not inherited settings:
To apply updated global push rules to existing projects, you must override the global push rules for each project individually.
[!note] If you delete push rules from a project, the project has no push rules at all. The project does not automatically inherit rules from the group or instance. To restore push rules, you must configure them again for the project.
You can create push rules that serve as a template for all new projects. You can override these rules in individual projects or groups.
When you configure global push rules:
Prerequisites:
To create global push rules:
{{< details >}}
{{< /details >}}
Group push rules allow group maintainers to set push rules for newly created projects in the specific group.
To configure push rules for a group:
New projects inherit push rules from:
Only projects inherit push rules. Subgroups don't inherit push rules from parent groups. To verify which push rules apply to new projects, create a project in the subgroup and check the project's push rules.
Project push rules are independent of global push rules. When you set push rules for a project, those rules replace any previously configured rules for that project.
To set push rules for a project:
For a project to match new global push rules, you must configure the project's push rules to match the global settings. Projects do not automatically inherit changes to global push rules.
Use these rules to validate users who make commits.
[!note] These push rules apply only to commits and not tags.
Reject unverified users: The committer email must match one of the user's verified email addresses or private commit email address.
Reject inconsistent user name: The commit author name must match the user's GitLab account name for commits where the author and committer emails are the same. The check is skipped when these emails differ, which occurs during workflows like cherry-picking or rebasing commits from other contributors.
This rule helps maintain commit hygiene by catching misconfigurations in users' Git settings, but does not prevent impersonation. For cryptographic identity verification, use Reject unsigned commits instead.
Check whether the commit author is a GitLab user: Both the commit author and committer email addresses must match a GitLab user's verified email addresses.
Commit author's email: Both the author and committer email addresses must match the regular expression. To allow any email address, leave empty.
When using bot users for projects or bot users for groups, you must add the generated email suffix so that bot tokens can commit and push changes.
Use these rules for your commit messages:
Require expression in commit messages: Messages must match the
expression. To allow any commit message, leave empty.
Uses multiline mode, which can be disabled by using (?-m). Some validation examples:
JIRA\-\d+ requires every commit to reference a Jira issue, like Refactored css. Fixes JIRA-123.[[:^punct:]]\b$ rejects a commit if the final character is a punctuation mark.
The word boundary character (\b) prevents false negatives, because Git adds a
newline character (\n) to the end of the commit message.Commit messages created in GitLab UI set \r\n as a newline character.
Use (\r\n?|\n) instead of \n in your regular expression to correctly match
it.
For example, given the following multi-line commit description:
JIRA:
Description
You can validate it with this regular expression: JIRA:(\r\n?|\n)\w+.
Reject expression in commit messages: Commit messages must not match
the expression. To allow any commit message, leave empty.
Uses multiline mode, which can be disabled by using (?-m).
To validate your branch names, enter a regular expression for Branch name. To allow any branch name, leave empty. Your default branch is always allowed. Certain formats of branch names are restricted by default for security purposes. Names with 40 hexadecimal characters, similar to Git commit hashes, are prohibited.
Some validation examples:
Branches must start with JIRA-.
^JIRA-
Branches must end with -JIRA.
-JIRA$
Branches must be between 4 and 15 characters long,
accepting only lowercase letters, numbers and dashes.
^[a-z0-9\\-]{4,15}$
Use these rules to prevent unintended consequences.
git push: Users cannot use git push to remove Git tags.Use these rules to validate files contained in the commit.
0. Files tracked by Git LFS are exempted.Never commit secrets, such as credential files and SSH private keys, to a version control system. In GitLab, you can use a predefined list of filename patterns to prevent matching files from being pushed to a repository. Merge requests that contain a matching file are blocked. This push rule does not restrict files already committed to the repository. You must update the configuration of existing projects to use the rule, using the process described in override global push rules per project.
Files blocked by this rule are listed below. For a complete list of criteria, refer to
files_denylist.yml.
.aws/credentialsaws/credentialshomefolder/aws/credentials/ssh/id_rsa/.ssh/personal_rsa/config/server_rsaid_rsa.id_rsa/ssh/id_dsa/.ssh/personal_dsa/config/server_dsaid_dsa.id_dsa/ssh/id_ed25519/.ssh/personal_ed25519/config/server_ed25519id_ed25519.id_ed25519/ssh/id_ecdsa/.ssh/personal_ecdsa/config/server_ecdsaid_ecdsa.id_ecdsa/ssh/id_ecdsa_sk/.ssh/personal_ecdsa_sk/config/server_ecdsa_skid_ecdsa_sk.id_ecdsa_sk/ssh/id_ed25519_sk/.ssh/personal_ed25519_sk/config/server_ed25519_skid_ed25519_sk.id_ed25519_sk*.pem*.key*.history*_historyIn Git, filenames include both the file's name, and all directories preceding the name.
When you git push, each filename in the push is compared to the regular expression
in Prohibited filenames.
[!note] This feature uses RE2 syntax, which does not support positive or negative lookaheads.
The regular expression can:
These examples use common regex string boundary patterns:
^: Matches the beginning of a string.$: Matches the end of a string.\.: Matches a literal period character. The backslash escapes the period.\/: Matches a literal forward slash. The backslash escapes the forward slash.To prevent pushing .exe files to any location in the repository:
\.exe$
To prevent pushing a specific configuration file:
In the repository root:
^config\.yml$
In a specific directory:
^directory-name\/config\.yml$
In any location - This example prevents pushing any file named install.exe:
(^|\/)install\.exe$
You can combine multiple patterns into one expression. This example combines all the previous expressions:
(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$
Signed commits are digital signatures used to verify the authenticity and integrity of Git commits. Use the Reject unsigned commits push rule to enforce signed commits for external contributors while allowing GitLab-created commits to remain unsigned.
When you enable the Reject unsigned commits push rule:
git push) must contain a valid cryptographic signature.
Unsigned commits are rejected.[!warning] Because commits created in GitLab are exempt from this rule, unsigned commits can still appear in your commit history even when the rule is enabled. The rule only validates commits pushed from external Git clients.
For more information, see issue 5361.
The signature must be created with a supported signing method:
Commits with invalid or corrupt signatures are rejected.
To enable the Reject unsigned commits push rule:
If a project has the Reject unsigned commits push rule, users cannot create commits through the GitLab Web IDE by default.
To allow committing through the Web IDE in a project with this push rule, a GitLab administrator
must disable the feature flag reject_unsigned_commits_by_gitlab:
Feature.disable(:reject_unsigned_commits_by_gitlab)
When this feature flag is disabled, commits created in the Web IDE are allowed without signatures. For more information, see enable or disable the feature.
Commits signed with the Developer Certificate of Origin (DCO)
certify the contributor wrote, or has the right to submit, the code contributed in that commit.
You can require all commits to your project to comply with the DCO. This push rule requires a
Signed-off-by: trailer in every commit message, and rejects any commits that lack it.
To update the push rules to be the same for all projects, use the Rails console, or write a script to update each project using the push rules API endpoint.
For example, to enable Check whether the commit author is a GitLab user and Do not allow users to remove Git tags with git push checkboxes,
and create a filter for allowing commits from a specific email domain only through rails console:
[!warning] Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
Project.find_each do |p|
pr = p.push_rule || PushRule.new(project: p)
# Check whether the commit author is a GitLab user
pr.member_check = true
# Do not allow users to remove Git tags with `git push`
pr.deny_delete_tag = true
# Commit author's email
pr.author_email_regex = '@domain\.com$'
pr.save!
end