"reviewdog" provides a way to post review comments to code hosting service, such as GitHub, automatically by integrating with any linter tools with ease. It uses an output of lint tools and posts them as a comment if findings are in diff of patches to review.
reviewdog also supports run in the local environment to filter an output of lint tools by diff.
- Installation
- Input Format
- reviewdog config file
- Reporters
- Reporter: Local (-reporter=local) [default]
- Reporter: GitHub Checks (-reporter=github-pr-check)
- Reporter: GitHub Checks (-reporter=github-check)
- Reporter: GitHub PullRequest review comment (-reporter=github-pr-review)
- Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion)
- Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit)
- Supported CI services
- Articles
# Install latest version. (Install it into ./bin/ by default).
$ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s
# Specify installation directory ($(go env GOPATH)/bin/) and version.
$ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b $(go env GOPATH)/bin [vX.Y.Z]
# In alpine linux (as it does not come with curl by default)
$ wget -O - -q https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s [vX.Y.Z]
or
$ go get -u github.com/reviewdog/reviewdog/cmd/reviewdog
You can also install reviewdog using brew:
$ brew install reviewdog/tap/reviewdog
$ brew upgrade reviewdog/tap/reviewdog
reviewdog accepts any compiler or linter result from stdin and parses it with scan-f like 'errorformat', which is the port of Vim's errorformat feature.
For example, if the result format is {file}:{line number}:{column number}: {message}
,
errorformat should be %f:%l:%c: %m
and you can pass it as -efm
arguments.
$ golint ./...
comment_iowriter.go:11:6: exported type CommentWriter should have comment or be unexported
$ golint ./... | reviewdog -efm="%f:%l:%c: %m" -diff="git diff master"
name | description |
---|---|
%f | file name |
%l | line number |
%c | column number |
%m | error message |
%% | the single '%' character |
... | ... |
Please see reviewdog/errorformat and :h errorformat if you want to deal with a more complex output. 'errorformat' can handle more complex output like a multi-line error message.
You can also try errorformat on the Playground!
By this 'errorformat' feature, reviewdog can support any tools output with ease.
But, you don't have to write 'errorformat' in many cases. reviewdog supports pre-defined errorformat for major tools.
You can find available errorformat name by reviewdog -list
and you can use it
with -f={name}
.
$ reviewdog -list
golint linter for Go source code - https://github.com/golang/lint
govet Vet examines Go source code and reports suspicious problems - https://golang.org/cmd/vet/
sbt the interactive build tool - http://www.scala-sbt.org/
...
$ golint ./... | reviewdog -f=golint -diff="git diff master"
You can add supported pre-defined 'errorformat' by contributing to reviewdog/errorformat
reviewdog also accepts checkstyle XML format as well. If the linter supports checkstyle format as a report format, you can use -f=checkstyle instead of using 'errorformat'.
# Local
$ eslint -f checkstyle . | reviewdog -f=checkstyle -diff="git diff"
# CI (overwrite tool name which is shown in review comment by -name arg)
$ eslint -f checkstyle . | reviewdog -f=checkstyle -name="eslint" -reporter=github-pr-check
Also, if you want to pass other Json/XML/etc... format to reviewdog, you can write a converter.
$ <linter> | <convert-to-checkstyle> | reviewdog -f=checkstyle -name="<linter>" -reporter=github-pr-check
reviewdog can also be controlled via the .reviewdog.yml configuration file instead of "-f" or "-efm" arguments.
With .reviewdog.yml, you can run the same commands both CI service and local environment including editor integration with ease.
runner:
<tool-name>:
cmd: <command> # (required)
errorformat: # (optional if there is supported format for <tool-name>. see reviewdog -list)
- <list of errorformat>
name: <tool-name> # (optional. you can overwrite <tool-name> defined by runner key)
level: <level> # (optional. same as -level flag. [info,warning,error])
# examples
golint:
cmd: golint ./...
errorformat:
- "%f:%l:%c: %m"
level: warning
govet:
cmd: go vet -all .
$ reviewdog -diff="git diff master"
project/run_test.go:61:28: [golint] error strings should not end with punctuation
project/run.go:57:18: [errcheck] defer os.Setenv(name, os.Getenv(name))
project/run.go:58:12: [errcheck] os.Setenv(name, "")
# You can use -runners to run only specified runners.
$ reviewdog -diff="git diff master" -runners=golint,govet
project/run_test.go:61:28: [golint] error strings should not end with punctuation
# You can use -conf to specify config file path.
$ reviewdog -conf=./.reviewdog.yml -reporter=github-pr-check
Output format for project config based run is one of the following formats.
<file>: [<tool name>] <message>
<file>:<lnum>: [<tool name>] <message>
<file>:<lnum>:<col>: [<tool name>] <message>
reviewdog can report results both in local environment and review services as continuous integration.
reviewdog can find newly introduced findings by filtering linter results
using diff. You can pass diff command as -diff
arg.
$ golint ./... | reviewdog -f=golint -diff="git diff master"
github-pr-check reporter reports results to GitHub Checks.
You can change report level for this reporter by level
field in config
file or -level
flag. You can control GitHub status
check result with this feature. (default: error)
Level | GitHub Status |
---|---|
info |
neutral |
warning |
neutral |
error |
failure |
There are two options to use this reporter.
Example: .github/workflows/reviewdog.yml
- name: Run reviewdog
env:
REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
golint ./... | reviewdog -f=golint -reporter=github-pr-check
See GitHub Actions section too. You can also use public reviewdog GitHub Actions.
reviewdog CLI send a request to reviewdog GitHub App server and the server post results as GitHub Checks, because Check API only supported for GitHub App and GitHub Actions.
- Install reviewdog Apps. https://github.com/apps/reviewdog
- Set
REVIEWDOG_TOKEN
or run reviewdog CLI in trusted CI providers.
- Get token from
https://reviewdog.app/gh/{owner}/{repo-name}
.
$ export REVIEWDOG_TOKEN="<token>"
$ reviewdog -reporter=github-pr-check
Note: Token is not required if you run reviewdog in Travis or AppVeyor.
Caution
As described above, github-pr-check reporter with Option 2 is depending on reviewdog GitHub App server. The server is running with haya14busa's pocket money for now and I may break things, so I cannot ensure that the server is running 24h and 365 days.
UPDATE: Started getting support by opencollective and GitHub sponsor. See Supporting reviewdog
github-pr-check reporter is better than github-pr-review reporter in general because it provides more rich feature and has less scope, but please bear in mind the above caution and please use it on your own risk.
You can use github-pr-review reporter if you don't want to depend on reviewdog server.
It's basically same as -reporter=github-pr-check
except it works not only for
Pull Request but also for commit and it reports results outside Pull Request
diff too.
You can create reviewdog badge for this reporter.
github-pr-review reporter reports results to GitHub PullRequest review comments using GitHub Personal API Access Token. GitHub Enterprise is supported too.
- Go to https://github.com/settings/tokens and generate new API token.
- Check
repo
for private repositories orpublic_repo
for public repositories.
$ export REVIEWDOG_GITHUB_API_TOKEN="<token>"
$ reviewdog -reporter=github-pr-review
For GitHub Enterprise, set API endpoint by environment variable.
$ export GITHUB_API="https://example.githubenterprise.com/api/v3/"
$ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL
See GitHub Actions section too if you can use GitHub Actions. You can also use public reviewdog GitHub Actions.
Required GitLab version: >= v10.8.0
gitlab-mr-discussion reporter reports results to GitLab MergeRequest discussions using
GitLab Personal API Access token.
Get the token with api
scope from https://gitlab.com/profile/personal_access_tokens.
$ export REVIEWDOG_GITLAB_API_TOKEN="<token>"
$ reviewdog -reporter=gitlab-mr-discussion
For self-hosted GitLab, set API endpoint by environment variable.
$ export GITLAB_API="https://example.gitlab.com/api/v4"
$ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL
gitlab-mr-commit is similar to gitlab-mr-discussion reporter but reports results to each commit in GitLab MergeRequest.
gitlab-mr-discussion is recommended, but you can use gitlab-mr-commit reporter if your GitLab version is under v10.8.0.
$ export REVIEWDOG_GITLAB_API_TOKEN="<token>"
$ reviewdog -reporter=gitlab-mr-commit
Example: .github/workflows/reviewdog.yml
name: reviewdog
on: [pull_request]
jobs:
reviewdog:
name: reviewdog
runs-on: ubuntu-latest
steps:
# ...
- name: Setup reviewdog
run: |
mkdir -p $HOME/bin && curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b $HOME/bin
echo ::add-path::$HOME/bin
echo ::add-path::$(go env GOPATH)/bin # for Go projects
- name: Run reviewdog
env:
REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
reviewdog -reporter=github-pr-check -runners=golint,govet
# or
reviewdog -reporter=github-pr-review -runners=golint,govet
Example (github-check reporter):
Only github-check
reporter can run on push event too.
name: reviewdog (github-check)
on:
push:
branches:
- master
pull_request:
jobs:
reviewdog:
name: reviewdog
runs-on: ubuntu-latest
steps:
# ...
- name: Run reviewdog
env:
REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
reviewdog -reporter=github-check -runners=golint,govet
You can use public GitHub Actions to start using reviewdog with ease! ๐
- Common
- Docker
- reviewdog/action-hadolint - Run hadolint to lint
Dockerfile
.
- reviewdog/action-hadolint - Run hadolint to lint
- Env
- mgrachev/action-dotenv-linter - Run dotenv-linter to lint
.env
files.
- mgrachev/action-dotenv-linter - Run dotenv-linter to lint
- Shell script
- Go
- reviewdog/action-golangci-lint - Run golangci-lint and supported linters individually by golangci-lint.
- JavaScript
- reviewdog/action-eslint - Run eslint.
- CSS
- Vim script
- reviewdog/action-vint - Run vint.
- tsuyoshicho/action-vimlint - Run vim-vimlint
- Terraform
- reviewdog/action-tflint - Run tflint.
- YAML
- Ruby
- reviewdog/action-brakeman - Run brakeman.
- reviewdog/action-rubocop - Run rubocop.
- Python
- wemake-python-styleguide - Run wemake-python-styleguide
- Kotlin
- ScaCap/action-ktlint - Run ktlint.
... and more on GitHub Marketplace.
Missing actions? Check out reviewdog/action-template and create a new reviewdog action!
Please open a Pull Request to add your created reviewdog actions here โจ. I can also put your repositories under reviewdog org and co-maintain the actions. Example: action-tflint.
GITHUB_TOKEN
for Pull Requests from forked repository doesn't have write
access to Check API nor Review API due to GitHub Actions
restriction.
Instead, reviewdog uses Logging commands of GitHub
Actions
to post results as
annotations
similar to github-pr-check
reporter.
Note that there is a limitation for annotations created by logging commands, such as max # of annotations per run. You can check GitHub Actions log to see full results in such cases.
As github-check
reporter support running on commit, we can create reviewdog
GitHub Action badge
to check the result against master commit for example. ๐
Example:
<!-- Replace <OWNWER> and <REPOSITORY>. It assumes workflow name is "reviewdog" -->
[![reviewdog](https://github.com/<OWNER>/<REPOSITORY>/workflows/reviewdog/badge.svg?branch=master&event=push)](https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3Areviewdog+event%3Apush+branch%3Amaster)
If you use -reporter=github-pr-check in Travis CI, you don't need to set REVIEWDOG_TOKEN
.
Example:
install:
- mkdir -p ~/bin/ && export export PATH="~/bin/:$PATH"
- curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ~/bin
script:
- reviewdog -conf=.reviewdog.yml -reporter=github-pr-check
Store GitHub API token by travis encryption keys.
$ gem install travis
$ travis encrypt REVIEWDOG_GITHUB_API_TOKEN=<token> --add env.global
Example:
env:
global:
- secure: <token>
install:
- mkdir -p ~/bin/ && export export PATH="~/bin/:$PATH"
- curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ~/bin
script:
- >-
golint ./... | reviewdog -f=golint -reporter=github-pr-review
Examples
Store REVIEWDOG_TOKEN
or REVIEWDOG_GITHUB_API_TOKEN
in
Environment variables - CircleCI
version: 2
jobs:
build:
docker:
- image: golang:latest
steps:
- checkout
- run: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ./bin
- run: go vet ./... 2>&1 | ./bin/reviewdog -f=govet -reporter=github-pr-check
# or
- run: go vet ./... 2>&1 | ./bin/reviewdog -f=govet -reporter=github-pr-review
Store REVIEWDOG_GITLAB_API_TOKEN
in GitLab CI variable.
reviewdog:
script:
- reviewdog -reporter=gitlab-mr-discussion
# Or
- reviewdog -reporter=gitlab-mr-commit
You can use reviewdog to post review comments from anywhere with following environment variables.
name | description |
---|---|
CI_PULL_REQUEST |
Pull Request number (e.g. 14) |
CI_COMMIT |
SHA1 for the current build |
CI_REPO_OWNER |
repository owner (e.g. "haya14busa" for https://github.com/haya14busa/reviewdog) |
CI_REPO_NAME |
repository name (e.g. "reviewdog" for https://github.com/haya14busa/reviewdog) |
CI_BRANCH |
[optional] branch of the commit |
$ export CI_PULL_REQUEST=14
$ export CI_REPO_OWNER=haya14busa
$ export CI_REPO_NAME=reviewdog
$ export CI_COMMIT=$(git rev-parse HEAD)
and set a token if required.
$ REVIEWDOG_TOKEN="<token>"
$ REVIEWDOG_GITHUB_API_TOKEN="<token>"
$ REVIEWDOG_GITLAB_API_TOKEN="<token>"
If a CI service doesn't provide information such as Pull Request ID - reviewdog can guess it by branch name and commit SHA.
Just pass the flag guess
:
$ reviewdog -conf=.reviewdog.yml -reporter=github-pr-check -guess
$ export CI_PULL_REQUEST=${ghprbPullId}
$ export CI_REPO_OWNER=haya14busa
$ export CI_REPO_NAME=reviewdog
$ export CI_COMMIT=${ghprbActualCommit}
$ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need
$ REVIEWDOG_TOKEN="<token>" reviewdog -reporter=github-pr-check
# Or
$ REVIEWDOG_GITHUB_API_TOKEN="<token>" reviewdog -reporter=github-pr-review
- reviewdog โ A code review dog who keeps your codebase healthy
- reviewdog โก GitHub Check โ improved automated review experience
- Automated Code Review on GitHub Actions with reviewdog for any languages/tools
Become GitHub Sponsor for each contributor or become a backer or sponsor from opencollective.