Commit Check GitHub Action

A GitHub Action for checking commit message formatting, branch naming, committer name, email, commit signoff, and more.

Table of Contents

• Usage
• Optional Inputs
• GitHub Action Job Summary
• GitHub Pull Request Comments
• Badging Your Repository
• Versioning

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/commit-check.yml

name: Commit Check

on:
  push:
  pull_request:
    branches: 'main'

jobs:
  commit-check:
    runs-on: ubuntu-latest
    permissions:  # use permissions because use of pr-comments
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: $  # checkout PR HEAD commit
          fetch-depth: 0  # required for merge-base check
      - uses: commit-check/commit-check-action@v1
        env:
          GITHUB_TOKEN: $ # use GITHUB_TOKEN because use of pr-comments
        with:
          message: true
          branch: true
          author-name: true
          author-email: true
          commit-signoff: true
          merge-base: false
          imperative: false
          job-summary: true
          pr-comments: $

Used By

Apache   discovery-unicamp   Texas Instruments   OpenCADC   Extrawest Chainlift   Mila   RLinf   and many more.

Optional Inputs

message

• Description: check commit message formatting convention.
  • By default, the rule follows Conventional Commits.
• Default: true

branch

• Description: check git branch naming convention.
  • By default, the rule follows Conventional Branch.
• Default: true

author-name

• Description: check committer author name.
• Default: true

author-email

• Description: check committer author email.
• Default: true

commit-signoff

• Description: check committer commit signature.
• Default: true

merge-base

• Description: check current branch is rebased onto the target branch.
• Default: false

Important: merge-base is an experimental feature. By default, it’s disabled.

To use this feature, you need to fetch all history for all branches by setting fetch-depth: 0 in actions/checkout.

imperative

• Description: check commit message is imperative mood.
• Default: false

dry-run

• Description: run checks without failing. exit code is 0; otherwise is 1.
• Default: false

job-summary

• Description: display job summary to the workflow run.
• Default: true

pr-comments

• Description: post results to the pull request comments.
• Default: false

Important: pr-comments is an experimental feature. By default, it’s disabled. To use it, you need to set GITHUB_TOKEN in the GitHub Action.

This feature currently doesn’t work with forked repositories. For more details, refer to issue #77.

Note: The default rule of above inputs follows this configuration. If you want to customize, just add your .commit-check.yml config file under your repository root directory.

GitHub Action Job Summary

By default, commit-check-action results are shown on the job summary page of the workflow.

Success Job Summary

Failure Job Summary

GitHub Pull Request Comments

Success Pull Request Comment

Failure Pull Request Comment

Badging Your Repository

You can add a badge to your repository to show your contributors/users that you use commit-check!

Markdown

[![Commit Check](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml)

reStructuredText

.. image:: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg
    :target: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml
    :alt: Commit Check

Advanced Examples

Minimal Setup

- uses: commit-check/commit-check-action@v1

Full Configuration

- uses: commit-check/commit-check-action@v1
  env:
    GITHUB_TOKEN: $
  with:
    message: true
    branch: true
    author-name: true
    author-email: true
    commit-signoff: true
    merge-base: true
    imperative: true
    job-summary: true
    pr-comments: true
    dry-run: false

Custom Workflow Example

name: Enhanced Commit Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  commit-check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          ref: $
          
      - name: Run commit check
        uses: commit-check/commit-check-action@v1
        env:
          GITHUB_TOKEN: $
        with:
          message: true
          branch: true
          author-name: true
          author-email: true
          commit-signoff: false
          merge-base: $
          imperative: true
          job-summary: true
          pr-comments: $

Versioning

Versioning follows Semantic Versioning.

Troubleshooting

Having issues? Check out our Troubleshooting Guide for common problems and solutions.

Have questions or feedback?

To provide feedback (requesting a feature or reporting a bug), please post to issues.

← Back to Main Documentation