README.md

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_target:
    branches: 'main'

jobs:
  commit-check:
    runs-on: ubuntu-latest
    permissions:  # use permissions because use of pr-comments
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ format('refs/pull/{0}/head', github.event.pull_request.number) }}  # checkout PR HEAD commit
          fetch-depth: 0  # required for merge-base check
          persist-credentials: false
      - uses: commit-check/commit-check-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.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: ${{ github.event_name == 'pull_request' || github.event_name == 'pull_request_target' }}

Used By

Apache   discovery-unicamp   Texas Instruments   OpenCADC   Extrawest Chainlift   Mila   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 and ensure your workflow has issues: write permission.

Note: the default rule of above inputs is following 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

Versioning

Versioning follows Semantic Versioning.

Have questions or feedback?

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