Skip to content

Push Rules

Available in GitLab Enterprise Editions.

Gain additional control over pushes to your repository.

Overview

GitLab already offers protected branches, but there are cases when you need some specific rules like preventing git tag removal or enforcing a special format for commit messages.

Push rules are essentially pre-receive Git hooks that are easy to enable in a user-friendly interface. They are defined globally if you are an admin or per project so you can have different rules applied to different projects depending on your needs.

Use cases

Every push rule could have its own use case, but let's consider some examples.

Commit messages with a specific reference

Let's assume you have the following requirements for your workflow:

  • every commit should reference a JIRA issue, for example: Refactored css. Fixes JIRA-123.
  • users should not be able to remove git tags with git push

All you need to do is write a simple regular expression that requires the mention of a JIRA issue in the commit message, like JIRA\-\d+.

Now when a user tries to push a commit with a message Bugfix, their push will be declined. Only pushing commits with messages like Bugfix according to JIRA-123 will be accepted.

Restrict branch names

Let's assume there's a strictly policy for branch names in your company, and you want the branches to start with a certain name because you have different GitLab CI jobs (feature, hotfix, docker, android, etc.) that rely on the branch name.

Your developers however, don't always remember that policy, so they push various branches and CI pipelines do not work as expected. By restricting the branch names globally in Push Rules, you can now sleep without the anxiety of your developers' mistakes. Every branch that doesn't match your push rule will get rejected.

Enabling push rules

Note: GitLab administrators can set push rules globally under Admin area > Push Rules that all new projects will inherit. You can later override them in a project's settings.

  1. Navigate to your project's Settings > Repository and expand Push Rules
  2. Set the rule you want
  3. Click Save Push Rules for the changes to take effect

The following options are available.

Push rule GitLab version Description
Removal of tags with git push EES 7.10 Forbid users to remove git tags with git push. Tags will still be able to be deleted through the web UI.
Check whether author is a GitLab user EES 7.10 Restrict commits by author (email) to existing GitLab users.
Check whether committer is the current authenticated user EEP 10.2 GitLab will reject any commit that was not committed by the current authenticated user
Check whether commit is signed through GPG EEP 10.1 Reject commit when it is not signed through GPG. Read signing commits with GPG.
Prevent committing secrets to Git EES 8.12 GitLab will reject any files that are likely to contain secrets. Read what files are forbidden.
Restrict by commit message EES 7.10 Only commit messages that match this Ruby regular expression are allowed to be pushed. Leave empty to allow any commit message.
Restrict by branch name EES 9.3 Only branch names that match this Ruby regular expression are allowed to be pushed. Leave empty to allow any branch name.
Restrict by commit author's email EES 7.10 Only commit author's email that match this Ruby regular expression are allowed to be pushed. Leave empty to allow any email.
Prohibited file names EES 7.10 Any committed filenames that match this Ruby regular expression are not allowed to be pushed. Leave empty to allow any filenames.
Maximum file size EES 7.12 Pushes that contain added or updated files that exceed this file size (in MB) are rejected. Set to 0 to allow files of any size.

Tip: You can check your regular expressions at http://rubular.com.

Prevent pushing secrets to the repository

Introduced in GitLab Enterprise Edition Starter 8.12.

You can turn on a predefined blacklist of files which won't be allowed to be pushed to a repository.

By selecting the checkbox Prevent committing secrets to Git, GitLab prevents pushes to the repository when a file matches a regular expression as read from files_blacklist.yml (make sure you are at the right branch as your GitLab version when viewing this file).

NOTE: Note: Files already committed won't get restricted by this push rule.

Below is an example list of what will be rejected by these regular expressions:

#####################
# AWS CLI credential blobs
#####################
.aws/credentials
aws/credentials
homefolder/aws/credentials

#####################
# Private RSA SSH keys
#####################
/ssh/id_rsa
/.ssh/personal_rsa
/config/server_rsa
id_rsa
.id_rsa

#####################
# Private DSA SSH keys
#####################
/ssh/id_dsa
/.ssh/personal_dsa
/config/server_dsa
id_dsa
.id_dsa

#####################
# Private ed25519 SSH keys
#####################
/ssh/id_ed25519
/.ssh/personal_ed25519
/config/server_ed25519
id_ed25519
.id_ed25519

#####################
# Private ECDSA SSH keys
#####################
/ssh/id_ecdsa
/.ssh/personal_ecdsa
/config/server_ecdsa
id_ecdsa
.id_ecdsa

#####################
# Any file with .pem or .key extensions
#####################
*.pem
*.key

#####################
# Any file ending with _history or .history extension
#####################
pry.history
bash_history