Skip to content

Enforcing Commit Message Standards

Version: Arctyk ITSM v0.6.0+
Last Updated: January 2026

This document explains how to ensure all pull requests follow the commit message conventions.

Overview

We use several mechanisms to enforce proper commit messages:

  1. GitHub PR Template - Reminds contributors of the commit guidelines
  2. commitlint - Automated validation in pull requests
  3. Pre-commit hooks - Local validation before pushing
  4. Branch protection rules - Enforce commit message validation

For Contributors

Setup Local Environment

Install pre-commit hooks to validate commits locally:

pip install pre-commit
pre-commit install --hook-type commit-msg

This will automatically validate your commit messages before they're created.

Before Pushing

Ensure your commits follow the format:

<type>: <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat: add email notifications for ticket assignments

- Implement Celery task for sending emails
- Add email templates
- Update ticket assignment view

Closes #42

If Your Commits Don't Follow the Convention

If GitHub Actions rejects your commits, you can fix them:

Option 1: Rebase and squash (recommended for small PRs)

git rebase -i HEAD~N  # N = number of commits to fix
# Change 'pick' to 'reword' for each commit
git push --force-with-lease

Option 2: Amend last commit

git commit --amend --no-edit
git push --force-with-lease

For Repository Maintainers

GitHub Actions Workflow

The commit-validation.yml workflow (in .github/workflows/):

  • Runs on every pull request
  • Validates all commit messages against the conventional commit format
  • Blocks PR merge if validation fails

Branch Protection Rules

Configure in Settings → Branches → Branch protection rules:

  1. Require status checks to pass:

  2. ✅ "Commit Message Validation"

  3. ✅ "Tests"

  4. ✅ "Linting"

  5. Require branches to be up to date before merging

  6. Require linear history (optional, keeps git history clean)

Commitlint Configuration

The commitlint.config.js file defines allowed types and rules. Modify it to match your conventions.

Troubleshooting

"commitlint: not found" locally

Install pre-commit hooks:

pip install pre-commit
pre-commit install --hook-type commit-msg

GitHub Actions failing but commits look correct

Check the workflow output - it may indicate:

  • Subject ends with period (remove it)
  • Type not in allowed list
  • Subject starts with capital letter (should be lowercase)

Need to merge a PR with non-compliant commits

Squash and rebase on merge:

  1. GitHub PR page → "Squash and merge"
  2. Fix the commit message in the dialog to follow the convention
  3. Complete the merge

Resources