Document use of commitlint as a github action (possible own CLI in the future)

[KnisterPeter]

Expected Behavior

Provide a github actions cli just like commitlint-travis.

Context

It should easy setup for running commitlint as part of a github actions setup.

[marionebl]

Yes, a Github action would be cool. Want to lend a hand with this?

[bennypowers]

I made this but have no idea if it works, since i'm not in the beta

https://github.com/bennypowers/commitlint-gh-actions

[KnisterPeter]

Nice, I can give it a try.

[bennypowers]

Added you to the repo. Do your worst 💃

[byCedric]

I'm accepted in the beta, so whatever happens, I can try it out too 😄 Also building some actions for Expo, but ran into some issues and trying to fix it with the GH team.

I think we also need to discuss where this will be hosted. We can do something like conventional-changelog/commitlint-action, I would be happy to submit it (officially) to the marketplace too! What do you guys think @marionebl @escapedcat?

[byCedric]

As a small side note, I would definitely recommend using the full LTS node version (node:10).

• Although it should only be used for commitlint, there were some implications with the official npm action. I did some benchmarking, it turned out that using the full version has no impact at all to the performance.
• There were also some strange issues with Jest/CRA and the latest Node 11 version, so the way I see it LTS versions are far more stable.

With these two minor, but good changes, the action covers more edge cases. I believe that was the main purpose of actions, make it simple and easy to use for everyone.

Or do you have a different opinion about this @bennypowers?

[escapedcat]

Agreed, I think it would be nice to have actions for CI environments.

[byCedric]

I think we should solve #613 and zero config before doing this right? That way, we can simply create an action with everything set to default. If projects have their own conventions, they simply need to add a npm install action before the commitlint action. Personally, I think this is the best approach for the actions. Or am I overthinking this?

[bennypowers]

@byCedric I have no strong opinion regarding node versions. probably newer is better. I can add you to the repo also

[byCedric]

Thanks! I'm trying to help out the guys at global-dirs, they make awesome reports on the issues (worth reading 😉). If this is resolved, I'll get started on the zero-config and this!

[bennypowers]

Ok, I published this

https://github.com/marketplace/actions/commitlint-cli

Haven't tried it out just yet 🙈

[wagoid]

I've created a github action for this that doesn't require any setup, if you want to have a look: https://github.com/marketplace/actions/commit-linter

I tried using @bennypowers's action but got some issues and ended up creating another one, as explained here

I am already using in some projects, feel free to use it too and let me know if anything goes wrong 😃

[arznaar]

I think you can also just call @commitlint/cli for this and get number of commits from PR event commitlint --from HEAD~${{ github.event.pull_request.commits }} --to HEAD and fetch all commits in checkout fetch-depth: 0. Here is full example:

on: [pull_request]
jobs:
  lint-commits:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
        with:
          # we actually need "github.event.pull_request.commits + 1" commit
          fetch-depth: 0
      - uses: actions/[email protected]
      # or just "yarn" if you depend on "@commitlint/cli" already
      - run: yarn add @commitlint/cli
      - run: yarn run commitlint --from HEAD~${{ github.event.pull_request.commits }} --to HEAD

[eladchen]

I was looking to lint all commit messages of a pull request and ended up using these steps:

      # https://github.com/actions/checkout
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.head.sha }}

      - name: lint
        run: |
          FIRST_COMMIT_SHA=$(curl -s -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" ${{ github.event.pull_request.commits_url }} | jq -r '.[0].sha')
          npm ci
          npx commitlint --from $FIRST_COMMIT_SHA^

The above step:

• Uses the commit URLs, and extracts the PR first commit SHA
• Calls commit lint CLI using '--from $FIRST_COMMIT_SHA^'
  Note: adding '^' is important in order to lint all commit messages, including the first.

P.S
The commits API authentication is facilitated by the built-in secret -> ${{ secrets.GITHUB_TOKEN }}

[ericis]

@eladchen very creative. Any reason you couldn't use the solution recommended by @arznaar and avoid the curl command?

[ericis]

@arznaar can you help me better understand the need for fetch-depth: 0 and how that relates to your PR commit comment? What happends if you don't include that?

[eladchen]

@eladchen very creative. Any reason you couldn't use the solution recommended by @arznaar and avoid the curl command?

@ericis
His solution will only be covering the last 20 commits, as that is a hard limit in the event payload

[arznaar]

@ericis

can you help me better understand the need for fetch-depth: 0

As we lint the whole PR history, we usually need more than 1 commit and in their readme, action/checkout fetches only one commit (https://github.com/actions/checkout/blob/592cf69a223b04e75ddf345919130b91010eb2a6/README.md):

Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set fetch-depth: 0 to fetch all history for all branches and tags

Not sure why my solution above would be limited to 20 commits, as I specifically avoid it by using HEAD~<numberOfCommits> from event to calculate PR source and it's strange that this number would be limited somehow. Looks like I need to play with it more, thanks @eladchen

[ericis]

Thanks @eladchen. Perhaps I'll just deny PRs with more than 20 commits in them hahah.

[ssbarnea]

Any change to get this sorted?

The documentation page from https://commitlint.js.org/#/guides-ci-setup does include guides only for Travis and Circle CI but fails to document how to setup Github Actions, a CI that is likely more popular than all others combined.

I was able to identify at least 3 different third party github actions on https://github.com/marketplace?query=commitlint but I do think that documenting a more or less official/recommended way of implementing the CI part would be highly useful for others.

AFAIK, it would ok to endorse an action implemented by someone else instead of not doing anything. We can always look into publishing our own action later.

[escapedcat]

Happy for a PR to at least point at a preferred 3rd party solution and document.

[ssbarnea]

@escapedcat How about a title like "Document use of commitlint as a github action". It should be generic enough.

BTW, For the moment I picked the one with most stars (~100) but I need to validate that it really prevents bad commits from passing.

[ajubin]

Hi, nothing was added to the doc, do you need some help to at least reference solutions and/or this solution #2568 (comment)

[escapedcat]

@ajubin yeah, happy if you could provide a PR to the docs here:
https://github.com/conventional-changelog/commitlint/blob/master/docs/guides-ci-setup.md

[mangkoran]

May I ask what is "^" used for in @eladchen solution?

Note: adding '^' is important in order to lint all commit messages, including the first.

[eladchen]

@mangkoran It's been a while since I've posted that answer.

As far as I remember it was needed to ensure the commit we're using as a ref would be included in the range of commits being processed by commitlint (inclusive/exclusive)

[mangkoran]

@eladchen Indeed you posted it a while ago, yet still did the trick for many people :D

So the "^" is commitlint syntax? Because I cannot find it in commitlint documentation

[escapedcat]

So the "^" is commitlint syntax? Because I cannot find it in commitlint documentation

It's a git syntax:

The other main way to specify a commit is via its ancestry. If you place a ^ (caret) at the end of a reference, Git resolves it to mean the parent of that commit.

[mangkoran]

I see. Thank you!

[escapedcat]

I assume this has been solved: https://commitlint.js.org/#/guides-ci-setup?id=github-actions