Skip to content

GitLab push rules and server hooks

Protected branches decide who can change a branch; push rules decide what may be pushed at all. A push rule is a check GitLab runs on every push before accepting it: does the branch name follow the convention, does each commit message match the agreed format, does it reference a Jira issue, is the author a verified user, does any file look like a private key? Unlike client-side Git hooks, nobody can skip them with --no-verify. When the built-in rules are not enough, administrators of GitLab Self-Managed can add server hooks: custom pre-receive scripts that run on the Git server.

The examples are for an invented OrdersPortal project that uses Jira keys like ORD-123. Rules and limits were checked against the GitLab documentation source for GitLab 19.x in November 2026. The regular expressions were tested with Python’s re module (their syntax is within what RE2 supports), and the server hook was run with Git 2.43 against a local bare repository.

Push rules require Premium or Ultimate on GitLab.com, Self-Managed and Dedicated. Server hooks are available in all tiers but only on GitLab Self-Managed.

Topic Enforces
How push rules apply Where rules are configured and how they are inherited.
Branch naming rules Names such as feature/ORD-123-refunds.
Commit message format Conventional Commits or another subject format.
Jira ID requirement Every commit references an issue key.
Files secrets and authors Blocked file names and sizes, secrets, verified authors, signed commits.
Pre-receive server hooks Anything the built-in rules cannot express.

Configure a project’s rules under Settings > Repository > Push rules (Maintainer or Owner role), a group’s under Settings > Repository > Pre-defined push rules, and the instance’s under Admin > Push rules. The important detail is that push rules work as templates, not live inheritance: global and group rules are copied into projects when the projects are created. Changing a group rule later does not update existing projects, subgroups do not inherit from parent groups, and deleting a project’s push rules leaves it with no rules at all rather than falling back to the group’s.

GitLab evaluates regular expressions with RE2 syntax, limited to 511 characters each. RE2 has no /pattern/flags form; put flags at the start, such as (?i) for case-insensitive matching. Rules are checked on push; commits that already exist in the repository are not re-validated.

Pitfalls:

  • Updating the group rule is not enough. To roll out a new rule to existing projects, update each project (the API helps for many projects).
  • Push rules are bypassed during fork synchronization. Updating a fork from upstream applies changes without validating them against the fork’s push rules.
  • Force pushes and deletions are not push rules. Block those with protected branches; the push rule for deletions only covers removing Git tags.

The Branch name rule rejects new branches whose names do not match a regular expression. The default branch is always allowed, and names made of 40 hexadecimal characters (which look like commit hashes) are always rejected. A pattern that requires a type prefix and a Jira key, or a numbered release branch:

^(feature|fix|hotfix)/[A-Z]+-[0-9]+(-[a-z0-9]+)*$|^release/[0-9]+\.[0-9]+$

Tested against sample names:

feature/ORD-123-refund-endpoint accepted
fix/ORD-9 accepted
release/2.4 accepted
Feature/ord-1 rejected
my-branch rejected
feature/ORD-123_Refund rejected

Matching is case-sensitive; (?i)^feature/ accepts any capitalization. Document the convention in CONTRIBUTING.md and use the same pattern in the project’s branch creation from issues.

Pitfalls:

  • Automation creates branches too. Dependency bots and release tooling use their own prefixes (for example renovate/); include them in the pattern or they will fail.
  • Anchor both ends. Without ^ and $, my-feature/ORD-1 matches a pattern meant to require the prefix.

Require expression in commit messages rejects any pushed commit whose message does not match; Reject expression in commit messages rejects messages that do match (for example (?i)^wip). Both use multiline mode by default, which means ^ matches the start of any line, not just the subject. To validate the subject line only, turn multiline off with (?-m) so ^ means the start of the message:

(?-m)^(feat|fix|docs|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9-]+\))?!?: \S

That pattern accepts feat(refunds): add refund endpoint and fix: round totals, and rejects added refunds. Commit messages created in the GitLab web UI use \r\n line endings, so match line breaks with (\r\n?|\n) rather than \n. Merge commits that GitLab creates (“Merge branch ‘feature/x’ into ‘main’”) must also pass, so either allow them with an alternative such as |^Merge branch or set a merge commit template in the project’s merge request settings that follows the format.

Give developers fast feedback on their own machines with the same pattern in a commit-msg hook (see Git hooks and commit conventions) and a commit template:

Terminal window
printf 'feat(scope): summary\n\nWhy this change is needed.\n\nRefs: ORD-\n' > .gitmessage
git config commit.template .gitmessage

Pitfalls:

  • Multiline mode makes rules too lenient. Without (?-m), a body line such as fix: typo satisfies a “subject must match” rule.
  • Every commit in the push is checked. One old non-conforming commit in a rebased branch blocks the whole push; fix it with an interactive rebase.

A Jira key requirement is a commit message rule. GitLab’s own example JIRA\-\d+ requires a fixed project key; a general pattern accepts any key:

\b[A-Z][A-Z0-9]+-[0-9]+\b

Because of multiline mode, the key can appear anywhere in the message, including a footer like Refs: ORD-123, which keeps subjects readable. Tested: feat(refunds): add refund endpoint with a body Refs ORD-123 passes, fix: round totals fails. Combine it with the branch naming rule so the key also appears in branch names, and use the GitLab Jira integration to link commits and MRs back to the issues. For merge request titles, use a description template reminder or a CI job that checks $CI_MERGE_REQUEST_TITLE.

Pitfalls:

  • Squash and merge commits need keys too. Make sure the squash commit message (from the MR title) and merge commit template contain the key.
  • Bots do not know your keys. Exempt bot commits with a separate path, such as a service account flow through merge requests, or the rule blocks automated updates.

The remaining push rules cover content and identity:

  • Prevent pushing secret files blocks files that match GitLab’s denylist of credential file names, such as .aws/credentials, id_rsa, id_ed25519 and other private SSH keys. It only checks new pushes, not files already in the repository.
  • Prohibited file names rejects new files whose paths match a regex, for example (?i)\.(exe|dll|pfx|jks)$.
  • Maximum file size (MB) rejects added or updated files over the limit; Git LFS files are exempt.
  • Reject unverified users, Check whether the commit author is a GitLab user and Commit author’s email (a regex) check identity; Reject unsigned commits requires signed commits; Reject commits that aren’t DCO certified requires a Signed-off-by trailer.
  • Do not allow users to remove Git tags with git push protects release tags from deletion.

For scanning file contents rather than names, GitLab’s secret push protection (Ultimate) checks commits for secrets during the push; it can be skipped for one push with git push -o secret_push_protection.skip_all, which is recorded in the audit log.

Pitfalls:

  • Name-based rules miss renamed secrets. A key saved as deploy.txt passes the secret file rule; content scanning catches more.
  • Signed-commit rules can block Web IDE commits. Commits created in the Web IDE may not be signed in the way the rule expects; check the documented exceptions before enabling it broadly.

On GitLab Self-Managed, administrators can attach custom Git server hooks (pre-receive, update, post-receive) to a repository or globally. A pre-receive hook reads one line per updated ref from standard input (<old-sha> <new-sha> <ref-name>) and rejects the entire push by exiting non-zero. Lines printed with the prefix GL-HOOK-ERR: are shown to the user in the terminal and the GitLab UI instead of the generic “pre-receive hook declined”.

Hooks are installed through Gitaly, not by copying files into the repository directory: package the script in a custom_hooks/ directory inside a tarball and run gitaly hooks set. Global hooks go in <custom_hooks_dir>/pre-receive.d/ and run in alphabetical order. GitLab provides environment variables such as GL_USERNAME, GL_PROJECT_PATH and GL_PROTOCOL.

This hook requires a Jira key in every new commit. Unlike the simple git log $oldrev..$newrev loop often shown, it handles new branches (old SHA all zeros) and deletions correctly:

#!/bin/sh
# custom_hooks/pre-receive: every new commit must reference a Jira key such as ORD-123
zero=0000000000000000000000000000000000000000
status=0
while read -r oldrev newrev refname; do
# Branch or tag deletion: nothing to check.
[ "$newrev" = "$zero" ] && continue
if [ "$oldrev" = "$zero" ]; then
# New branch: only check commits that no existing branch already has.
range="$newrev --not --branches"
else
range="$oldrev..$newrev"
fi
for commit in $(git rev-list $range); do
subject=$(git log -1 --format=%s "$commit")
if ! printf '%s\n' "$subject" | grep -Eq '\b[A-Z][A-Z0-9]+-[0-9]+\b'; then
echo "GL-HOOK-ERR: $(echo "$commit" | cut -c1-8) on $refname has no Jira key: '$subject'. Example: 'ORD-123: add refund endpoint'."
status=1
fi
done
done
exit $status

Install it on one repository (Linux package installation; storage name and relative path come from the admin area):

Terminal window
mkdir custom_hooks && cp pre-receive custom_hooks/ && chmod +x custom_hooks/pre-receive
tar -cf custom_hooks.tar custom_hooks
cat custom_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set \
--storage default --repository <relative-path> --config /var/opt/gitlab/gitaly/config.toml

Tested locally on a bare repository: a branch with one commit missing a key is rejected, and after amending the message the push succeeds.

remote: GL-HOOK-ERR: 96cf0948 on refs/heads/feature/ORD-123-refunds has no Jira key: 'tidy up'. Example: 'ORD-123: add refund endpoint'.
! [remote rejected] feature/ORD-123-refunds -> feature/ORD-123-refunds (pre-receive hook declined)
error: failed to push some refs to '../srv.git'

Pitfalls:

  • Hooks are not replicated. Gitaly Cluster needs the hook on every node, and Geo does not replicate server hooks to secondary sites.
  • Keep hooks fast and dependency-free. They run on every push to the server; a slow or crashing hook blocks everyone. Any runtime a hook needs must be installed on each Gitaly server.
  • Not on GitLab.com. If you cannot run the gitaly command, use push rules, CI jobs or webhooks instead.
Need Use
Branch names, commit formats, Jira keys Push rules (Premium, Ultimate)
Who can push, merge or force push Protected branches
Secrets by file name Push rule “Prevent pushing secret files”
Secrets by content Secret push protection (Ultimate)
Logic the built-in rules cannot express, on Self-Managed Pre-receive server hook
Feedback before the push Client-side commit-msg and pre-commit hooks

Why might changing a group’s push rules have no effect on an existing project? Push rules are copied into projects when they are created. Existing projects keep their own copy, so the new rule must be applied to each project individually.

A “subject must start with feat or fix” rule lets Update README through. Why? Commit message rules run in multiline mode, so ^ matches at the start of any line; a body line starting with fix: satisfies the pattern. Start the expression with (?-m) to anchor it to the beginning of the message.

What is the difference between push rules and server hooks? Push rules are built-in, configured in the UI, available on GitLab.com and Self-Managed (Premium and Ultimate). Server hooks are custom scripts installed by administrators through Gitaly on Self-Managed only, for checks the built-in rules cannot express.

How does a pre-receive hook handle a newly created branch? The old SHA is all zeros, so old..new is invalid. Check the commits reachable from the new SHA that are not on any existing branch (git rev-list <new> --not --branches), and skip deletions where the new SHA is all zeros.

Senior scenario: you must introduce a Jira-key rule across 200 existing projects without breaking open merge requests. How? Announce the format and add client-side hooks and an MR template first. Apply the commit message rule through the API to each project, starting with a pilot group. Because rules check new pushes only, existing history is unaffected, but open MRs with non-conforming commits will fail on the next push; give teams a window and instructions for rewording with interactive rebase. Make sure squash and merge commit templates include the key and exempt service accounts through a merge request flow rather than weakening the regex.