Need help with reviewdog?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

reviewdog
3.2K Stars 169 Forks MIT License 2.2K Commits 55 Opened issues

Description

🐶 Automated code review tool integrated with any code analysis tools regardless of programming language

Services available

!
?

Need anything else?

Contributors list

reviewdog - A code review dog who keeps your codebase healthy.


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.

design doc

Table of Contents

github-pr-check sample comment in pull-request commit status sample-comment.png reviewdog-local-demo.gif

Installation

# Install the 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]

Nightly releases

You can also use nightly reviewdog release to try the latest reviewdog improvements every day!

$ curl -sfL https://raw.githubusercontent.com/reviewdog/nightly/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

GitHub Action: reviewdog/action-setup

steps:
- uses: reviewdog/[email protected]
  with:
    reviewdog_version: latest # Optional. [latest,nightly,v.X.Y.Z]

homebrew / linuxbrew

You can also install reviewdog using brew:

$ brew install reviewdog/tap/reviewdog
$ brew upgrade reviewdog/tap/reviewdog

Build from HEAD with go get

$ go get -u github.com/reviewdog/reviewdog/cmd/reviewdog

Input Format

'errorformat'

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 FETCH_HEAD"

| 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.

Available pre-defined 'errorformat'

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 FETCH_HEAD"

You can add supported pre-defined 'errorformat' by contributing to reviewdog/errorformat

Reviewdog Diagnostic Format (RDFormat)

reviewdog supports Reviewdog Diagnostic Format (RDFormat) as a generic diagnostic format and it supports both rdjson and rdjsonl formats.

This rdformat supports rich feature like multiline ranged comments, severity, rule code with URL, and code suggestions.

$  |  | reviewdog -f=rdjson -reporter=github-pr-review
# or
$  |  | reviewdog -f=rdjsonl -reporter=github-pr-review

Example: ESLint with RDFormat

eslint reviewdog rdjson demo

You can use eslint-formatter-rdjson to output

rdjson
as eslint output format.
$ npm install --save-dev eslint-formatter-rdjson
$ eslint -f rdjson . | reviewdog -f=rdjson -reporter=github-pr-review

Or you can also use reviewdog/action-eslint for GitHub Actions.

Diff

reviewdog with gofmt example

reviewdog supports diff (unified format) as an input format especially useful for code suggestions. reviewdog can integrate with any code suggestions tools or formatters to report suggestions.

-f.diff.strip
: option for
-f=diff
: strip NUM leading components from diff file names (equivalent to 'patch -p') (default is 1 for git diff) (default 1)
$  # e.g. eslint --fix, gofmt
$ TMPFILE=$(mktemp)
$ git diff >"${TMPFILE}"
$ git stash -u && git stash drop
$ reviewdog -f=diff -f.diff.strip=1 -reporter=github-pr-review < "${TMPFILE}"

Or you can also use reviewdog/action-suggester for GitHub Actions.

If diagnostic tools support diff output format, you can pipe the diff directly.

$ gofmt -s -d . | reviewdog -name="gofmt" -f=diff -f.diff.strip=0 -reporter=github-pr-review
$ shellcheck -f diff $(shfmt -f .) | reviewdog -f=diff

checkstyle format

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-check

Also, if you want to pass other Json/XML/etc... format to reviewdog, you can write a converter.

$  |  | reviewdog -f=checkstyle -name="" -reporter=github-pr-check

Code Suggestions

eslint reviewdog suggestion demo reviewdog with gofmt example

reviewdog supports code suggestions feature with rdformat or diff input. You can also use reviewdog/action-suggester for GitHub Actions.

reviewdog can suggest code changes along with diagnostic results if a diagnostic tools supports code suggestions data. You can integrate reviewdog with any code fixing tools and any code formatter with diff input as well.

Code Suggestions Support Table

Note that not all reporters provide support of code suggestion.

|

-reporter
| Suggestion support | | ---------------------------- | ------- | |
local
| NO [1] | |
github-check
| NO [2] | |
github-pr-check
| NO [2] | |
github-pr-review
| OK | |
gitlab-mr-discussion
| NO [1] | |
gitlab-mr-commit
| NO [2] | |
gerrit-change-review
| NO [1] | |
bitbucket-code-report
| NO [2] |
  • [1] The reporter service support code suggestion feature, but reviewdog does not support it yet. See #678 for the status.
  • [2] The reporter service itself doesn't support code suggestion feature.

reviewdog config file

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.

.reviewdog.yml

runner:
  :
    cmd:  # (required)
    errorformat: # (optional if you use `format`)
      - 
    format:  # (optional if you use `errorformat`. e.g. golint,rdjson,rdjsonl)
    name:  # (optional. you can overwrite  defined by runner key)
    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 . format: govet your-awesome-linter: cmd: awesome-linter run format: rdjson name: AwesomeLinter

$ reviewdog -diff="git diff FETCH_HEAD"
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 FETCH_HEAD" -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.

  • : [] 
  • :: [] 
  • ::: [] 

Reporters

reviewdog can report results both in local environment and review services as continuous integration.

Reporter: Local (-reporter=local) [default]

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 FETCH_HEAD"

Reporter: GitHub Checks (-reporter=github-pr-check)

github-pr-check sample annotation with option 1 github-pr-check sample

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.

Option 1) Run reviewdog from GitHub Actions w/ secrets.GITHUB_TOKEN

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.

Option 2) Install reviewdog GitHub Apps

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.

  1. Install reviewdog Apps. https://github.com/apps/reviewdog
  2. Set
    REVIEWDOG_TOKEN
    or run reviewdog CLI in trusted CI providers.
    • Get token from
      https://reviewdog.app/gh/{owner}/{repo-name}
      .
$ export REVIEWDOG_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 depends 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

You can use github-pr-review reporter or use run reviewdog under GitHub Actions if you don't want to depend on reviewdog server.

Reporter: GitHub Checks (-reporter=github-check)

It's basically same as

-reporter=github-pr-check
except it works not only for Pull Request but also for commit.

sample comment outside diff

You can create reviewdog badge for this reporter.

Reporter: GitHub PullRequest review comment (-reporter=github-pr-review)

sample-comment.png

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 or
    public_repo
    for public repositories.
$ export REVIEWDOG_GITHUB_API_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.

Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion)

gitlab-mr-discussion sample

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/personalaccesstokens.
$ export REVIEWDOG_GITLAB_API_TOKEN=""
$ reviewdog -reporter=gitlab-mr-discussion

The

CI_API_V4_URL
environment variable, defined automatically by Gitlab CI (v11.7 onwards), will be used to find out the Gitlab API URL.

Alternatively,

GITLAB_API
can also be defined, in which case it will take precedence over
CI_API_V4_URL
.
$ export GITLAB_API="https://example.gitlab.com/api/v4"
$ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL

Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit)

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=""
$ reviewdog -reporter=gitlab-mr-commit

Reporter: Gerrit Change review (-reporter=gerrit-change-review)

gerrit-change-review reporter reports result to Gerrit Change using Gerrit Rest APIs.

The reporter supports Basic Authentication and Git-cookie based authentication for reporting results.

Set

GERRIT_USERNAME
and
GERRIT_PASSWORD
environment variables for basic authentication, and put
GIT_GITCOOKIE_PATH
for git cookie based authentication.
$ export GERRIT_CHANGE_ID=changeID
$ export GERRIT_REVISION_ID=revisionID
$ export GERRIT_BRANCH=master
$ export GERRIT_ADDRESS=http://:
$ reviewdog -reporter=gerrit-change-review

Reporter: Bitbucket Code Insights Reports (-reporter=bitbucket-code-report)

bitbucket-code-report bitbucket-code-annotations

bitbucket-code-report generates the annotated Bitbucket Code Insights report.

For now, only the

no-filter
mode supported, so the whole project is scanned on every run. Reports are stored per commit and can be viewed per commit from Bitbucket Pipelines UI or in Pull Request. In the Pull Request UI affected code lines will be annotated in the diff, as well as you will be able to filter the annotations by This pull request or All.

If running from Bitbucket Pipelines, no additional configuration is needed (even credentials). If running locally or from some other CI system you would need to provide Bitbucket API credentials:

  • For Basic Auth you need to set following env variables:
    BITBUCKET_USER
    and
    BITBUCKET_PASSWORD
  • For AccessToken Auth you need to set
    BITBUCKET_ACCESS_TOKEN
$ export BITBUCKET_USER="my_user"
$ export BITBUCKET_PASSWORD="my_password"
$ reviewdog -reporter=bitbucket-code-report

Supported CI services

GitHub Actions

Example: .github/workflows/reviewdog.yml

name: reviewdog
on: [pull_request]
jobs:
  reviewdog:
    name: reviewdog
    runs-on: ubuntu-latest
    steps:
      # ...
      - uses: reviewdog/[email protected]
        with:
          reviewdog_version: latest # Optional. [latest,nightly,v.X.Y.Z]
      - 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):

.github/workflows/reviewdog

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

Public Reviewdog GitHub Actions

You can use public GitHub Actions to start using reviewdog with ease! :tada: :arrow_forward: :tada:

... 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 :sparkles:. I can also put your repositories under reviewdog org and co-maintain the actions. Example: action-tflint.

Graceful Degradation for Pull Requests from forked repositories

Graceful Degradation example

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.

reviewdog badge reviewdog

As

github-check
reporter support running on commit, we can create reviewdog GitHub Action badge to check the result against master commit for example. :tada:

Example:

[![reviewdog](https://github.com///workflows/reviewdog/badge.svg?branch=master&event=push)](https://github.com///actions?query=workflow%3Areviewdog+event%3Apush+branch%3Amaster)

Travis CI

Travis CI (-reporter=github-pr-check)

If you use -reporter=github-pr-check in Travis CI, you don't need to set

REVIEWDOG_TOKEN
.

Example:

install:
  - mkdir -p ~/bin/ && 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

Travis CI (-reporter=github-pr-review)

Store GitHub API token by travis encryption keys.

$ gem install travis
$ travis encrypt REVIEWDOG_GITHUB_API_TOKEN= --add env.global

Example:

env:
  global:
    - secure: 

install:

script:

  • >- golint ./... | reviewdog -f=golint -reporter=github-pr-review

Examples

  • https://github.com/azu/textlint-reviewdog-example

  • Circle CI

    Store

    REVIEWDOG_GITHUB_API_TOKEN
    (or
    REVIEWDOG_TOKEN
    for github-pr-check) in Environment variables - CircleCI

    .circleci/config.yml sample

    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-review
    
    
      # Deprecated: prefer GitHub Actions to use github-pr-check reporter.
      - run: go vet ./... 2&gt;&amp;1 | ./bin/reviewdog -f=govet -reporter=github-pr-check

    GitLab CI

    Store

    REVIEWDOG_GITLAB_API_TOKEN
    in GitLab CI variable.

    .gitlab-ci.yml sample

    reviewdog:
      script:
        - reviewdog -reporter=gitlab-mr-discussion
        # Or
        - reviewdog -reporter=gitlab-mr-commit
    

    Bitbucket Pipelines

    No additional configuration is needed.

    bitbucket-pipelines.yml sample

    pipelines:
      default:
        - step:
            name: Reviewdog
            image: golangci/golangci-lint:v1.31-alpine
            script:
              - wget -O - -q https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | 
                  sh -s -- -b $(go env GOPATH)/bin
              - golangci-lint run --out-format=line-number ./... | reviewdog -f=golangci-lint -reporter=bitbucket-code-report
    

    Common (Jenkins, local, etc...)

    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=""
    $ REVIEWDOG_GITHUB_API_TOKEN=""
    $ REVIEWDOG_GITLAB_API_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
    

    Jenkins with Github pull request builder plugin

    $ 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="" reviewdog -reporter=github-pr-check
    # Or
    $ REVIEWDOG_GITHUB_API_TOKEN="" reviewdog -reporter=github-pr-review
    

    Exit codes

    By default reviewdog will return

    0
    as exit code even if it finds errors. If
    -fail-on-error
    flag is passed, reviewdog exits with
    1
    when at least one error was found/reported. This can be helpful when you are using it as a step in your CI pipeline and want to mark the step failed if any error found by linter.

    See also

    -level
    flag for github-pr-check/github-check reporters. reviewdog will exit with
    1
    if reported check status is
    failure
    as well if
    -fail-on-error=true
    .

    Filter mode

    reviewdog filter results by diff and you can control how reviewdog filter results by

    -filter-mode
    flag. Available filter modes are as below.

    added
    (default)

    Filter results by added/modified lines.

    diff_context

    Filter results by diff context. i.e. changed lines +-N lines (N=3 for example).

    file

    Filter results by added/modified file. i.e. reviewdog will report results as long as they are in added/modified file even if the results are not in actual diff.

    nofilter

    Do not filter any results. Useful for posting results as comments as much as possible and check other results in console at the same time.

    -fail-on-error
    also works with any filter-mode and can catch all results from any linters with
    nofilter
    mode.

    Example:

    shell
    $ reviewdog -reporter=github-pr-review -filter-mode=nofilter -fail-on-error
    

    Filter Mode Support Table

    Note that not all reporters provide full support of filter mode due to API limitation. e.g.

    github-pr-review
    reporter uses GitHub Review API but it doesn't support posting comment outside diff (
    diff_context
    ), so reviewdog will use Check annotation as fallback to post those comments [1].

    |

    -reporter
    \
    -filter-mode
    |
    added
    |
    diff_context
    |
    file
    |
    nofilter
    | | ---------------------------- | ------- | -------------- | ----------------------- | ---------- | |
    local
    | OK | OK | OK | OK | |
    github-check
    | OK | OK | OK | OK | |
    github-pr-check
    | OK | OK | OK | OK | |
    github-pr-review
    | OK | OK | Partially Supported [1] | Partially Supported [1] | |
    gitlab-mr-discussion
    | OK | OK | OK | Partially Supported [2] | |
    gitlab-mr-commit
    | OK | Partially Supported [2] | Partially Supported [2] | Partially Supported [2] | |
    gerrit-change-review
    | OK | OK? [3] | OK? [3] | Partially Supported? [2][3] | |
    bitbucket-code-report
    | NO [4] | NO [4] | NO [4] | OK |
    • [1] Report results which is outside diff context with Check annotation as fallback if it's running in GitHub actions instead of Review API (comments). All results will be reported to console as well.
    • [2] Report results which is outside diff file to console.
    • [3] It should work, but not verified yet.
    • [4] Not implemented at the moment

    Debugging

    Use the

    -tee
    flag to show debug info.
    reviewdog -filter-mode=nofilter -tee
    

    Articles

    :bird: Author

    haya14busa GitHub followers

    Contributors

    Contributors

    Supporting reviewdog

    Become GitHub Sponsor for each contributor or become a backer or sponsor from opencollective.

    Become a backer

    We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.