Commitlint Github Action

Lints Pull Request commits with commitlint

Usage

Create a github workflow in the .github folder, e.g. .github/workflows/commitlint.yml:

name: Commitlint
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v1

Alternatively, you can run on other event types such as on: [push]. In that case the action will lint the push event's commit(s) instead of linting commits from a pull request. You can also combine push and pull_request together in the same workflow.

Note: It's necessary that you specify the fetch-depth argument to actions/checkout@v2 step. By default they fetch only latest commit of the branch, but we need more commits since we validate a range of commit messages.

Inputs

configFile

The path to your commitlint config file.

Default: commitlint.config.js

firstParent

When set to true, we follow only the first parent commit when seeing a merge commit.

This helps to ignore errors in commits that were already present in your default branch (e.g. master) before adding conventional commit checks. More info in git-log docs.

Default: true

failOnWarnings

Whether you want to fail on warnings or not.

Default: false

helpURL

Link to a page explaining your commit message convention.

default: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

Outputs

results

The error and warning messages for each one of the analyzed commits. This is useful if you want to use the commitlint results in a JSON format in other jobs. See the documentation on how to read JSON information from outputs.

Below you can see an example text output together with its corresponding JSON output:

You have commit messages with errors

⧗   input: wrong message
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

⧗   input: chore: my message
⚠   body must have leading blank line [body-leading-blank]

⚠   found 0 problems, 1 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

[
  {
    "hash": "cb0f846f13b490c2fd17bd5ed0b6f65ba9b86c75",
    "message": "wrong message",
    "valid": false,
    "errors": ["subject may not be empty", "type may not be empty"],
    "warnings": [],
  },
  {
    "hash": "cb14483cbde23b61322ffb8d3fcdc87f514a3141",
    "message": "chore: my message\n\nsome context without leading blank line",
    "valid": true,
    "errors": [],
    "warnings": ["body must have leading blank line"],
  },
]

About extends in your config file

This is a Docker action, and was made like this so that you can run it with minimum setup, regardless of your repo's environment. It comes packed with the most famous shared configurations that you can use in your commitlint config's extends field:

• @commitlint/config-angular
• @commitlint/config-conventional
• @commitlint/config-lerna-scopes
• @commitlint/config-patternplate
• conventional-changelog-lint-config-canonical
• commitlint-config-jira

Apart from the shared configurations that are included by default, you can also include extra dependencies for other configs and plugins that you want to use.

In order to do so, you can use NODE_PATH env var to make the action take those dependencies into account. Below is an example workflow that does that.

name: Commitlint
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v1
        with:
          node-version: '10.x'
      - run: npm install
      - name: Add dependencies for commitlint action
        # $GITHUB_WORKSPACE is the path to your repository
        run: echo "::set-env name=NODE_PATH::$GITHUB_WORKSPACE/node_modules"
      # Now the commitlint action will run considering its own dependencies and yours as well 🚀
      - uses: wagoid/commitlint-github-action@v1

---

💡 You can see other ways to install your dependencies (including private ones) in the Setup Node action's docs.

---