How to fix remote: error: pre-receive hook declined in Git

The pre-receive hook error is often accompanied by additional context. Look for lines starting with "remote:" before the hook declined message:

# Example output with context:
remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Required status check "ci/tests" is expected.
remote: error: pre-receive hook declined

The lines above "pre-receive hook declined" tell you exactly what rule was violated. Common prefixes include:
- GH006: GitHub protected branch violation
- GitLab: Push rules or protected branch issues
- Custom: Organization-specific validation messages

If you're pushing to a protected branch (usually main/master), verify the protection rules:

GitHub:
1. Go to repository Settings > Branches > Branch protection rules
2. Check if the branch matches a protection rule
3. Verify if "Require pull request reviews" is enabled
4. Check if you have bypass permissions

GitLab:
1. Go to Settings > Repository > Protected branches
2. Check "Allowed to push" settings for your branch
3. Verify your role (Maintainer vs Developer)

Bitbucket:
1. Go to Repository settings > Branch permissions
2. Review which users/groups can push directly

If the branch is protected, create a feature branch and open a pull/merge request instead:

# Create a new branch from your current changes
git checkout -b feature/my-changes

# Push the feature branch
git push -u origin feature/my-changes

# Then create a PR/MR through the web interface

Check that you have the correct role to push to the target branch:

GitLab roles:
- Guest/Reporter: Cannot push
- Developer: Can push to unprotected branches
- Maintainer/Owner: Can push to protected branches

GitHub roles:
- Read: Cannot push
- Triage/Write: Can push to unprotected branches
- Maintain/Admin: Can push to protected branches or bypass rules

To check your current access:

# Test your SSH connection to verify you're using the right account
ssh -T [email protected]
ssh -T [email protected]

# Check the remote URL
git remote -v

If you need elevated permissions, contact the repository administrator or owner.

If your organization requires specific commit message formats, amend your commits to comply:

# Amend the most recent commit message
git commit --amend -m "JIRA-123: Add new feature"

# Interactive rebase to edit multiple commits
git rebase -i HEAD~3

# In the editor, change 'pick' to 'reword' for commits needing new messages
# Save and follow prompts to enter new messages

Common commit message requirements:
- JIRA/Ticket numbers: PROJ-123: description
- Conventional commits: feat: add new feature
- Signed-off-by lines: git commit -s

After amending, force push to your branch (if allowed):

git push --force-with-lease origin your-branch

Note: Never force push to shared branches without team coordination.

If the error mentions file size limits, remove large files from your commit history:

# Find large files in your repository
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print $3, $4}' | sort -rn | head -20

# Remove a large file from the last commit
git reset --soft HEAD~1
git rm --cached large-file.zip
git commit -m "Your commit message"

# Remove from entire history (use with caution)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch path/to/large-file.zip" \
  --prune-empty --tag-name-filter cat -- --all

For future large files, use Git LFS:

# Install and configure Git LFS
git lfs install
git lfs track "*.zip"
git add .gitattributes

If the error is related to non-fast-forward updates, sync your branch first:

# Fetch latest changes
git fetch origin

# Rebase your changes on top of remote
git pull --rebase origin main

# Or merge if you prefer
git pull origin main

# Then push
git push origin main

If you have conflicts:

# After resolving conflicts
git add .
git rebase --continue

# Then push
git push origin main

Some platforms require commits to be authored by verified email addresses:

# Check your Git email configuration
git config user.email

# Check the email in your commits
git log --format='%ae' -1

# Update your Git email to match your account
git config --global user.email "[email protected]"

# Amend the last commit with correct email
git commit --amend --reset-author --no-edit

# For multiple commits, use interactive rebase
git rebase -i HEAD~5 --exec "git commit --amend --reset-author --no-edit"

Verify your email is confirmed on your Git hosting platform (Settings > Emails).

Sometimes the error is caused by temporary server issues:

Check service status:
- GitHub: https://www.githubstatus.com/
- GitLab: https://status.gitlab.com/
- Bitbucket: https://bitbucket.status.atlassian.com/

If the service is experiencing issues, wait and retry later:

# Wait a few minutes, then retry
git push origin main

You can also check if it's a network issue on your end:

# Test SSH connectivity
ssh -T [email protected]

# Test HTTPS connectivity
curl -I https://github.com