GitLab "pre-receive hook declined": why your push was rejected

By Melih Toksari, developer of MergeBell · Updated · 5 min read

Short answer

"! [remote rejected] main -> main (pre-receive hook declined)" means one of GitLab's checks refused the push before anything changed, and the "remote: GitLab:" lines just above it say which. The usual causes are a protected branch; on GitLab.com Free, a file of 100 MiB or more, which belongs in Git LFS; secret push protection on Ultimate, "PUSH BLOCKED: Secrets detected in code changes"; push rules on Premium and Ultimate, such as a commit message or committer email that doesn't match; Git LFS objects that were never uploaded; and a repository over its size limit, 10 GB on GitLab.com. Fix the commits it names and push again. Removing a file in a new commit isn't enough, because the commit that added it is still part of the push.

You push, and GitLab refuses:

 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'https://gitlab.com/group/project.git'

pre-receive hook declined only says that one of GitLab’s checks refused the push, before any branch changed. The reason is on the remote: GitLab: lines just above it. Here’s what each one means in GitLab 19.5, and how to get the push through.

What the remote: lines say

The remote: line starts with Cause Applies to
You are not allowed to push code to protected branches A protected branch Every tier
You are attempting to check in one or more files which exceed the 100MiB limit A big file GitLab.com Free
PUSH BLOCKED: Secrets detected in code changes Secret push protection Ultimate
… does not follow the pattern …, or You cannot push commits for … A push rule Premium, Ultimate
LFS objects are missing. Git LFS files never uploaded Projects with Git LFS
Your push to this repository cannot be completed … The repository size limit 10 GB on GitLab.com
The default branch of a project cannot be deleted. A delete or git push --mirror Every tier

Each check looks at every commit in the push, not just the last one. If an earlier commit added a big file or a secret, deleting it in a new commit isn’t enough: rewrite the commit that added it.

A protected branch

remote: GitLab: You are not allowed to push code to protected branches on this project.

Your role isn’t allowed to push to that branch. A force push gets its own message, You are not allowed to force push code to a protected branch on this project., whenever the branch doesn’t allow force pushes, whatever your role. Push to a new branch and open a merge request instead. Every protected-branch message, including the one for a new project’s first commit, is in GitLab “not allowed to push code to protected branches”.

A file of 100 MiB or more

remote: GitLab: You are attempting to check in one or more files which exceed the 100MiB limit:

- 257cc5642cb1a054f08cc83f2d943e56fd3ebe99 (123 MiB)

On GitLab.com, projects on the Free tier can’t take new files of 100 MiB or more. The list shows each file’s blob ID, not its name. To find the file:

git rev-list --objects --all | grep 257cc5642cb1a054f08cc83f2d943e56fd3ebe99

Large binary files belong in Git LFS. To move a file that’s already in commits you haven’t pushed into LFS, rewrite them, then push again:

git lfs migrate import --include="*.zip"

It rewrites only the branch you have checked out, and only commits that aren’t on the remote yet, so run it on each branch you push.

A secret in the push

remote: PUSH BLOCKED: Secrets detected in code changes
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
remote:
remote: -- test.txt:2 GitLab Personal Access Token

Secret push protection, on Ultimate, found a token or key. Remove it from every commit that has it, with git commit --amend for the last commit or git rebase -i for older ones, and revoke it if it’s real: it was on its way to the server.

If it’s a placeholder or a false positive, skip the check for this push:

git push -o secret_push_protection.skip_all

Or add [skip secret push protection] to one of the commit messages, which works from any Git client, including the Web IDE. GitLab records every skip as an audit event.

A push rule

Push rules, on Premium and Ultimate, live under Settings › Repository › Push rules. Common ones:

  • Commit messages: a required or forbidden pattern. Reword the commits with git commit --amend or git rebase -i. Every commit in the push must pass, not just the last one.
  • Branch names: the branch must match a pattern. Rename it with git branch -m.
  • Reject unverified users: each commit’s committer email must be one of your verified emails, or your private commit email. GitLab says You cannot push commits for that address. Set git config user.email, then rewrite the commits, such as git commit --amend --reset-author --no-edit for the last one. If the address is yours but not verified yet, GitLab says so instead: verify it under your profile’s Emails.
  • Commit author’s email: both emails must match a pattern, and the message says the email does not follow the pattern.
  • Reject unsigned commits: every commit must be signed.
  • Maximum file size (MB) and Prohibited file names: files of that size or larger, or with a forbidden name. Files tracked by Git LFS are exempt from the size rule.

Ask a Maintainer if a rule is wrong for your work: they can change the project’s rules.

Git LFS objects are missing

remote: GitLab: LFS objects are missing. Ensure LFS is properly set up or try a manual "git lfs push --all".

The push has Git LFS pointer files, but GitLab doesn’t have the files they point to. That’s common when you push a clone or a mirror to a new project. A fresh clone usually doesn’t have every LFS file, so fetch them from the old remote first, then upload them and push again:

git lfs fetch --all old-origin
git lfs push --all origin

Run git lfs install first if Git LFS isn’t set up on your machine. If your LFS files live on another server, GitLab can’t check them: turn off Git LFS for the project instead.

The repository is too big

remote: GitLab: Your push to this repository cannot be completed because this repository has exceeded the allocated storage for your project. Contact your GitLab administrator for more information.

The repository, including Git LFS files, is over its size limit: 10 GB on GitLab.com. If this push would take it over, the message ends as it would exceed the allocated storage for your project instead. On GitLab Self-Managed and Dedicated, administrators set the limit, on Premium and Ultimate. Make the repository smaller, for example by removing large files from its history, or buy more storage.

Other causes

  • The default branch. The default branch of a project cannot be deleted. comes from a push that deletes it, often git push --mirror from a repository whose default branch has another name.
  • Branch names like commit IDs. GitLab refuses to create a branch named like a commit SHA: You cannot create a branch with a SHA-1 or SHA-256 branch name.
  • Custom server hooks. On GitLab Self-Managed, administrators can add their own hooks. GitLab shows a hook’s explanation only from lines that start with GL-HOOK-ERR:; without one, ask the administrator.

If Git fails earlier, with HTTP Basic: Access denied or Permission denied (publickey), GitLab never got to these checks: see why GitLab rejects Git credentials.

On your phone

A rejected push happens in your terminal, so the fix starts there. Once your branch is pushed, MergeBell shows the merge request, its pipeline and its approvals on your phone, and you can approve and merge from there on the free tier. See how to review a GitLab merge request on your phone.

Frequently asked questions

What does "pre-receive hook declined" mean in GitLab?

GitLab ran its checks on your push before updating any branch, and one of them refused it, so nothing was pushed. The reason is in the "remote: GitLab:" lines just above the rejected line: a protected branch, a file over GitLab.com's 100 MiB limit, a secret, a push rule, missing Git LFS objects or the repository size limit. On GitLab Self-Managed, an administrator's custom server hook can also refuse a push with its own message.

How do I push a file larger than 100 MiB to GitLab.com?

On GitLab.com, projects on the Free tier can't take new files of 100 MiB or more. Track the file with Git LFS instead. If it's already in a commit you haven't pushed, rewrite that commit, for example with git lfs migrate import --include="*.zip", because deleting the file in a later commit leaves it in the push.

How do I fix "PUSH BLOCKED: Secrets detected in code changes" in GitLab?

Remove the secret from every commit in the push, with git commit --amend for the last commit or an interactive rebase for older ones, and revoke the secret if it's real. If it's a placeholder or a false positive, skip the check with git push -o secret_push_protection.skip_all, or add [skip secret push protection] to a commit message. GitLab records each skip as an audit event.

Why does GitLab say "LFS objects are missing" when I push?

The push contains Git LFS pointer files whose objects GitLab doesn't have, often when you push a clone or a mirror to a new project. A fresh clone usually doesn't have all the LFS files either, so fetch them from where they are, with git lfs fetch --all followed by that remote's name, then upload them with git lfs push --all origin and push again. If your LFS files live on another server, turn off Git LFS for the project instead.

How do I fix "You cannot push commits for" an email address in GitLab?

The project's Reject unverified users push rule requires each commit's committer email to be one of your verified emails or your private commit email. Set git config user.email to one of them, rewrite the commits, for example git commit --amend --reset-author --no-edit for the last one, and push again.

Sources

Checked against these pages on 11 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.