How to fix remote: GitLab: Commit message does not follow the pattern in Git

What this error means

The error "remote: GitLab: Commit message does not follow the pattern" means your GitLab repository or group has **push rules** configured that enforce a specific commit message format. When you push commits, GitLab validates each commit message against a regular expression pattern, and if any commit doesn't match, the entire push is rejected. Push rules are a GitLab feature that helps teams enforce commit message conventions. Common requirements include: - Referencing issue/ticket numbers (e.g., "JIRA-123", "Fixes #456") - Following conventional commit formats (e.g., "feat:", "fix:", "docs:") - Including specific keywords or project identifiers This is a server-side validation that cannot be bypassed without changing your commit message or having an admin modify the push rules. The error will show you the exact regex pattern that your commit message failed to match.

Typical symptoms

• Push to GitLab fails with 'Commit message does not follow the pattern' error
• Error shows a regex pattern like 'JIRA-\d+' or 'workitem \d+'
• Initial commits to new projects are rejected
• Merge trains fail with commit message validation errors
• semantic-release or automated tools fail when pushing
• Push succeeds on one branch but fails on another with different rules
• CI/CD pipelines fail during push operations
• Git notes pushes are rejected by commit message rules

Common causes

1. Commit message doesn't include required issue/ticket reference number
2. Commit message format doesn't match the required conventional commit style
3. Group or project-level push rules require specific patterns you're unaware of
4. Merge commit messages created by GitLab UI don't match the pattern
5. Automated tools like semantic-release or Renovate push commits without required format
6. Git notes are being validated against commit message rules
7. Multi-line commit messages use different newline characters than the regex expects
8. You inherited global push rules when creating a new project

How to fix "remote: GitLab: Commit message does not follow the pattern"

# The error typically looks like:
remote: GitLab: Commit message does not follow the pattern 'JIRA-\d+'
# Or
remote: GitLab: Commit message does not follow the pattern 'workitem \d+'
# Or
remote: GitLab: Commit message does not follow the pattern '^(feat|fix|docs|style|refactor|test|chore):'

# Amend the last commit with a new message
git commit --amend -m "JIRA-123: Add initial project setup"

# Or for conventional commit format
git commit --amend -m "feat: add initial project setup (#123)"

# Or open an editor to modify the message
git commit --amend

# Then force push if you already pushed the old commit
git push --force-with-lease

# Rebase the last N commits (e.g., last 3)
git rebase -i HEAD~3

# In the editor, change 'pick' to 'reword' for commits you want to edit:
# reword abc1234 Initial commit
# pick def5678 Add feature
# reword ghi9012 Fix bug

# Save and close. Git will pause at each 'reword' commit
# Edit each message to include the required pattern

# After completing the rebase, force push
git push --force-with-lease

# If pattern '^Merge.*$' fails on merge trains,
# the admin can adjust to handle GitLab's auto-generated format
^(Merge|feat|fix|docs|chore|refactor|test|style):?.*

# Create a commit-msg hook
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/bash

# Pattern required by your GitLab (adjust to match your rules)
PATTERN="JIRA-[0-9]+"

MESSAGE=$(cat "$1")

if ! echo "$MESSAGE" | grep -qE "$PATTERN"; then
    echo "ERROR: Commit message must contain a JIRA ticket (e.g., JIRA-123)"
    echo "Your message: $MESSAGE"
    exit 1
fi
EOF

chmod +x .git/hooks/commit-msg

# In your project root
mkdir -p .githooks
# Add your commit-msg hook there

# Configure git to use it
git config core.hooksPath .githooks

# Commit the hooks to share with team
git add .githooks

// In your release.config.js, format commits to match push rules
module.exports = {
  plugins: [
    ['@semantic-release/commit-analyzer', {
      releaseRules: [
        { type: 'feat', release: 'minor' },
        { type: 'fix', release: 'patch' }
      ]
    }],
    ['@semantic-release/release-notes-generator'],
    ['@semantic-release/git', {
      // Customize commit message to match your pattern
      message: 'chore(release): ${nextRelease.version} [skip ci] JIRA-0'
    }]
  ]
};

{
  "commitMessagePrefix": "JIRA-0: ",
  "commitMessageTopic": "{{depName}}"
}

# Push notes separately with a different configuration
GIT_NOTES_REF=refs/notes/commits git push origin refs/notes/*

Advanced notes

JIRA-\d+
# Matches: JIRA-123, feat: add login JIRA-456
# Fails: Initial commit, fix bug

^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:
# Matches: feat: add login, fix(auth): resolve bug
# Fails: Add new feature, Fixed the bug

(closes?|fixes?|resolves?)\s+#\d+
# Matches: closes #123, Fixes #456
# Fails: Add feature, Updated docs

^Merge branch
# Rejects auto-generated merge commit messages

^\[?WIP\]?
# Rejects: WIP: working on feature, [WIP] testing

[[:^punct:]]\b$
# The word boundary prevents false negatives from trailing newlines

# View your commit messages before pushing
git log --oneline origin/main..HEAD

# Test a message against a pattern locally
echo "Your commit message" | grep -E "JIRA-\d+"

# See the full commit message
git log -1 --format=%B

Frequently asked questions

What does "remote: GitLab: Commit message does not follow the pattern" mean?

The error "remote: GitLab: Commit message does not follow the pattern" means your GitLab repository or group has push rules configured that enforce a specific commit message format. When you push commits, GitLab validates each commit message against a regular expression pattern, and if any commit doesn't match, the entire push is rejected. Push rules are a GitLab feature that helps teams enforce commit message conventions.

How do I fix "remote: GitLab: Commit message does not follow the pattern"?

This error occurs when GitLab push rules reject your commit because the commit message doesn't match the required regex pattern. You need to amend your commit message to include required elements like issue numbers, ticket references, or specific formats.

What causes "remote: GitLab: Commit message does not follow the pattern"?

Commit message doesn't include required issue/ticket reference number Commit message format doesn't match the required conventional commit style Group or project-level push rules require specific patterns you're unaware of

Is the "remote: GitLab: Commit message does not follow the pattern" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• remote: GitLab: File size exceeds maximum allowed size

  How to fix 'File size exceeds maximum allowed size' in GitLab

  MEDIUM

• remote: GitLab: The project is archived and cannot be modified

  How to fix 'The project is archived and cannot be modified' in Git

  MEDIUM

• remote: GitLab: Push was rejected because it contains secrets

  How to fix 'Push was rejected because it contains secrets' in GitLab

  HIGH

• remote: GitLab: Namespace storage limit has been reached

  How to fix "Namespace storage limit has been reached" in GitLab

  HIGH

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  GitLab Docs - Push Rules(Official Docs)
• 💬
  Stack Overflow - Can't push to GitLab, commit message does not follow the pattern(Stack Overflow)
• 💬
  GitLab Forum - Can't push to repo, does not follow the pattern(Stack Overflow)
• 💬
  GitLab Forum - Push rule preventing merge train from running(Stack Overflow)
• 🐙
  semantic-release - GitLab fails when Push Rules for commit messages is enabled(GitHub)
• 📖
  GitLab Docs - Merge Request Commits(Official Docs)