Useful GitHub Actions to help build software. Detailed documentation on how to use each action located on their folder.

Adding linters on the PR is as simple as adding an action to resolve on push.

Linters don't need access to GITHUB_TOKEN, but they might need extra secrets and env-vars, depending on how the tool is used.

For example, cljfmt needs to be installed and setup on the project, as well as any environment variable to access the project's dependencies. Meanwhile ,shellcheck needs no modification on the project to be adopted.

Check the documentation of the action to see if it is necessary to setup the project before adoption.

Here is an example workflow:

workflow "on push" {
  on = "push"
  resolves = ["shellcheck"]
}

action "shellcheck" {
  uses = "bltavares/actions/shellcheck@master"
}

It is possible to add linters which observe the Review comments and act upon them. This uses the pull_request_review event, and it expects the fix <action> as the content.

Given this workflow, you could trigger the fix as the following:

workflow "on reviews" {
  on = "pull_request_review"
  resolves = ["cljfmt"]
}

action "cljfmt" {
  uses = "bltavares/actions/cljfmt@master"
  secrets = ["GITHUB_TOKEN"]
}

The even only works on Review comments, not on regular PR comments.

This is a limitation of the information provided on the event payload, which Review comments are run on the PR context, while regular comments on the PR are run pointing to master, with no reference to the branch being discussed.

(So far I'm not aware how to make it work for both scenarios with the information provided)

It is possible to add linters which will automatically fix itself. It does so by using the underlying autofix, commiting and running the lints right after.

Running a second time allows the check to validate if the automatic changes fixed all the warnings, as some warnings cannot be automated by the underlying tool.

This uses the push event, and it can be enabled using the args = ["autofix"].

workflow "on reviews" {
  on = "pull_request_review"
  resolves = ["shfmt"]
}

action "shfmt" {
  uses = "bltavares/actions/shfmt@master"
  args = ["autofix"]
  secrets = ["GITHUB_TOKEN"]
}

Autofixes requires a certain level of coordination when building the workflow. Given that each action runes and modify the code, they need to be sequential, otherwise a data race might lead to lost commits.

The autofixers might run in parallel of other linters, but not in parallel of other autofixers.

Here is an example of how to chain fixers on a workflow, while still having parallel linters running.

workflow "on push" {
  on = "push"
  resolves = ["linters", "autofixers"]
}

action "linters" {
  needs = ["mdlint", "shellcheck"]
  uses = "actions/bin/sh@master"
  args = ["echo Linters ok"]
}

action "autofixers" {
  needs = ["shfmt", "cljfmt"]
  uses = "actions/bin/sh@master"
  args = ["echo Fixers ok"]
}

action "shfmt" {
  uses = "bltavares/actions/shfmt@master"
  args = ["autofix"]
  secrets = ["GITHUB_TOKEN"]
  needs = ["cljfmt"]
}

action "cljfmt" {
  uses = "bltavares/actions/cljfmt@master"
  args = ["autofix"]
  secrets = ["GITHUB_TOKEN"]
}

action "mdlint" {
  uses = "bltavares/actions/mdlint@master"
}

action "shellcheck" {
  uses = "bltavares/actions/shellcheck@master"
}

This would generate the following pipeline:

And would result on the following example on pushes:

You may validate the ordering of fixers using act -l locally, provided by nektos/act.

Autofixers listening to push events will execute both on pull requests, as well as commits pointing to master. If there is no restriction, on master commits the autofixers will also commit the changes to master.

This might not be the workflow you are looking for. You may use actions/bin/filter to restrict wheter autofixers should run or not, leveraing the ref filter and branch filter

Here is one example, using autofixers only on PRs, while using them as linters on master.

workflow "on push" {
  on = "push"
  resolves = ["linters", "autofixers"]
}

action "linters" {
  needs = ["mdlint", "shellcheck", "shfmt-lint", "cljfmt-lint"]
  uses = "actions/bin/sh@master"
  args = ["echo Linters ok"]
}

action "autofixers" {
  needs = ["shfmt", "cljfmt"]
  uses = "actions/bin/sh@master"
  args = ["echo Fixers ok"]
}

action "pr filter" {
  uses = "actions/bin/filter@master"
  args = "ref refs/pulls/*"
}

action "master filter" {
  uses = "actions/bin/filter@master"
  args = "branch master"
}

action "fixers-lint" {
  uses = "actions/bin/filter@master"
  args = "branch master"
}

action "shfmt" {
  uses = "bltavares/actions/shfmt@master"
  args = ["autofix"]
  secrets = ["GITHUB_TOKEN"]
  needs = ["cljfmt", "pr filter"]
}

action "cljfmt" {
  uses = "bltavares/actions/cljfmt@master"
  args = ["autofix"]
  secrets = ["GITHUB_TOKEN"]
  needs = ["pr filter"]
}

action "shfmt-lint" {
  uses = "bltavares/actions/shfmt@master"
  needs = ["master filter"]
}

action "cljfmt-lint" {
  uses = "bltavares/actions/cljfmt@master"
  needs = ["master filter"]
}

action "mdlint" {
  uses = "bltavares/actions/mdlint@master"
}

action "shellcheck" {
  uses = "bltavares/actions/shellcheck@master"
}

It is possible to test the actions and execute locally using nektos/act.

If the workflow contains linters, they will execute on the same context as GitHub Actions would, allowing to use them as a quick feedback tool.

Alternatively, if autofixers are present on your project workflow, not only they will execute the linter, but it will commit and push their fixes from your machine as well.

⚠️ Autofixers will commit any dirty tree state if run locally. Only run them on clean branches if you want to keep the git history clean.

This make them effective pre-commit hooks that either run remotely or locally.

This project uses nektos/act to test changes locally, and requires it to be installed.

To keep all the lib.sh updated and validate the project itself, run:

make

If you need to skip linting, as it might need to copy the lib before properly linting:

make -W lint