github.com/friedemannf/reviewdog@v0.14.0/README.md (about) 1 <div align="center"> 2 <a href="https://github.com/friedemannf/reviewdog"> 3 <img alt="reviewdog" src="https://raw.githubusercontent.com/haya14busa/i/d598ed7dc49fefb0018e422e4c43e5ab8f207a6b/reviewdog/reviewdog.logo.png"> 4 </a> 5 </div> 6 7 <h2 align="center"> 8 reviewdog - A code review dog who keeps your codebase healthy. 9 </h2> 10 11 <div align="center"> 12 <a href="./LICENSE"> 13 <img alt="LICENSE" src="https://img.shields.io/badge/license-MIT-blue.svg?maxAge=43200"> 14 </a> 15 <a href="https://godoc.org/github.com/friedemannf/reviewdog"> 16 <img alt="GoDoc" src="https://img.shields.io/badge/godoc-reference-4F73B3.svg?label=godoc.org&maxAge=43200&logo=go"> 17 </a> 18 <a href="./CHANGELOG.md"> 19 <img alt="releases" src="https://img.shields.io/github/release/reviewdog/reviewdog.svg?logo=github"> 20 </a> 21 <a href="https://github.com/reviewdog/nightly"> 22 <img alt="nightly releases" src="https://img.shields.io/github/v/release/reviewdog/nightly.svg?logo=github"> 23 </a> 24 </div> 25 26 <div align="center"> 27 <a href="https://github.com/friedemannf/reviewdog/actions?query=workflow%3AGo+event%3Apush+branch%3Amaster"> 28 <img alt="GitHub Actions" src="https://github.com/friedemannf/reviewdog/workflows/Go/badge.svg"> 29 </a> 30 <a href="https://github.com/friedemannf/reviewdog/actions?query=workflow%3Areviewdog+event%3Apush+branch%3Amaster"> 31 <img alt="reviewdog" src="https://github.com/friedemannf/reviewdog/workflows/reviewdog/badge.svg?branch=master&event=push"> 32 </a> 33 <a href="https://github.com/friedemannf/reviewdog/actions?query=workflow%3Arelease"> 34 <img alt="release" src="https://github.com/friedemannf/reviewdog/workflows/release/badge.svg"> 35 </a> 36 <a href="https://travis-ci.org/reviewdog/reviewdog"><img alt="Travis Status" src="https://img.shields.io/travis/reviewdog/reviewdog/master.svg?label=Travis&logo=travis"></a> 37 <a href="https://circleci.com/gh/reviewdog/reviewdog"><img alt="CircleCI Status" src="http://img.shields.io/circleci/build/github/reviewdog/reviewdog/master.svg?label=CircleCI&logo=circleci"></a> 38 <a href="https://codecov.io/github/reviewdog/reviewdog"><img alt="Coverage Status" src="https://img.shields.io/codecov/c/github/reviewdog/reviewdog/master.svg?logo=codecov"></a> 39 </div> 40 41 <div align="center"> 42 <a href="https://gitlab.com/reviewdog/reviewdog/pipelines"> 43 <img alt="GitLab Supported" src="https://img.shields.io/badge/GitLab%20-Supported-fc6d26?logo=gitlab"> 44 </a> 45 <a href="https://github.com/haya14busa/action-bumpr"> 46 <img alt="action-bumpr supported" src="https://img.shields.io/badge/bumpr-supported-ff69b4?logo=github&link=https://github.com/haya14busa/action-bumpr"> 47 </a> 48 <a href="https://github.com/reviewdog/.github/blob/master/CODE_OF_CONDUCT.md"> 49 <img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"> 50 </a> 51 <a href="https://somsubhra.github.io/github-release-stats/?username=reviewdog&repository=reviewdog&per_page=30"> 52 <img alt="Github Releases Stats" src="https://img.shields.io/github/downloads/reviewdog/reviewdog/total.svg?logo=github"> 53 </a> 54 <a href="https://starcharts.herokuapp.com/reviewdog/reviewdog"><img alt="Stars" src="https://img.shields.io/github/stars/reviewdog/reviewdog.svg?style=social"></a> 55 </div> 56 <br /> 57 58 reviewdog provides a way to post review comments to code hosting service, 59 such as GitHub, automatically by integrating with any linter tools with ease. 60 It uses an output of lint tools and posts them as a comment if findings are in 61 diff of patches to review. 62 63 reviewdog also supports run in the local environment to filter an output of lint tools 64 by diff. 65 66 [design doc](https://docs.google.com/document/d/1mGOX19SSqRowWGbXieBfGPtLnM0BdTkIc9JelTiu6wA/edit?usp=sharing) 67 68 ## Table of Contents 69 70 - [Installation](#installation) 71 - [Input Format](#input-format) 72 * ['errorformat'](#errorformat) 73 * [Available pre-defined 'errorformat'](#available-pre-defined-errorformat) 74 * [Reviewdog Diagnostic Format (RDFormat)](#reviewdog-diagnostic-format-rdformat) 75 * [Diff](#diff) 76 * [checkstyle format](#checkstyle-format) 77 - [Code Suggestions](#code-suggestions) 78 - [reviewdog config file](#reviewdog-config-file) 79 - [Reporters](#reporters) 80 * [Reporter: Local (-reporter=local) [default]](#reporter-local--reporterlocal-default) 81 * [Reporter: GitHub Checks (-reporter=github-pr-check)](#reporter-github-checks--reportergithub-pr-check) 82 * [Reporter: GitHub Checks (-reporter=github-check)](#reporter-github-checks--reportergithub-check) 83 * [Reporter: GitHub PullRequest review comment (-reporter=github-pr-review)](#reporter-github-pullrequest-review-comment--reportergithub-pr-review) 84 * [Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion)](#reporter-gitlab-mergerequest-discussions--reportergitlab-mr-discussion) 85 * [Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit)](#reporter-gitlab-mergerequest-commit--reportergitlab-mr-commit) 86 * [Reporter: Bitbucket Code Insights Reports (-reporter=bitbucket-code-report)](#reporter-bitbucket-code-insights-reports--reporterbitbucket-code-report) 87 - [Supported CI services](#supported-ci-services) 88 * [GitHub Actions](#github-actions) 89 * [Travis CI](#travis-ci) 90 * [Circle CI](#circle-ci) 91 * [GitLab CI](#gitlab-ci) 92 * [Bitbucket Pipelines](#bitbucket-pipelines) 93 * [Common (Jenkins, local, etc...)](#common-jenkins-local-etc) 94 + [Jenkins with Github pull request builder plugin](#jenkins-with-github-pull-request-builder-plugin) 95 - [Exit codes](#exit-codes) 96 - [Filter mode](#filter-mode) 97 - [Articles](#articles) 98 99 [![github-pr-check sample](https://user-images.githubusercontent.com/3797062/40884858-6efd82a0-6756-11e8-9f1a-c6af4f920fb0.png)](https://github.com/friedemannf/reviewdog/pull/131/checks) 100 ![comment in pull-request](https://user-images.githubusercontent.com/3797062/40941822-1d775064-6887-11e8-98e9-4775d37d47f8.png) 101 ![commit status](https://user-images.githubusercontent.com/3797062/40941738-d62acb0a-6886-11e8-858d-7b97aded2a42.png) 102 [![sample-comment.png](https://raw.githubusercontent.com/haya14busa/i/dc0ccb1e110515ea407c146d99b749018db05c45/reviewdog/sample-comment.png)](https://github.com/friedemannf/reviewdog/pull/24#discussion_r84599728) 103 ![reviewdog-local-demo.gif](https://raw.githubusercontent.com/haya14busa/i/dc0ccb1e110515ea407c146d99b749018db05c45/reviewdog/reviewdog-local-demo.gif) 104 105 ## Installation 106 107 ```shell 108 # Install the latest version. (Install it into ./bin/ by default). 109 $ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s 110 111 # Specify installation directory ($(go env GOPATH)/bin/) and version. 112 $ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b $(go env GOPATH)/bin [vX.Y.Z] 113 114 # In alpine linux (as it does not come with curl by default) 115 $ wget -O - -q https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s [vX.Y.Z] 116 ``` 117 118 ### Nightly releases 119 120 You can also use [nightly reviewdog release](https://github.com/reviewdog/nightly) 121 to try the latest reviewdog improvements every day! 122 123 ```shell 124 $ curl -sfL https://raw.githubusercontent.com/reviewdog/nightly/master/install.sh | sh -s -- -b $(go env GOPATH)/bin 125 ``` 126 127 ### GitHub Action: [reviewdog/action-setup](https://github.com/reviewdog/action-setup) 128 129 ```yaml 130 steps: 131 - uses: reviewdog/action-setup@v1 132 with: 133 reviewdog_version: latest # Optional. [latest,nightly,v.X.Y.Z] 134 ``` 135 136 ### homebrew / linuxbrew 137 You can also install reviewdog using brew: 138 139 ```shell 140 $ brew install reviewdog/tap/reviewdog 141 $ brew upgrade reviewdog/tap/reviewdog 142 ``` 143 144 ### Build with go install 145 146 ```shell 147 $ go install github.com/friedemannf/reviewdog/cmd/reviewdog@latest 148 ``` 149 150 ## Input Format 151 152 ### 'errorformat' 153 154 reviewdog accepts any compiler or linter result from stdin and parses it with 155 scan-f like [**'errorformat'**](https://github.com/reviewdog/errorformat), 156 which is the port of Vim's [errorformat](https://vim-jp.org/vimdoc-en/quickfix.html#error-file-format) 157 feature. 158 159 For example, if the result format is `{file}:{line number}:{column number}: {message}`, 160 errorformat should be `%f:%l:%c: %m` and you can pass it as `-efm` arguments. 161 162 ```shell 163 $ golint ./... 164 comment_iowriter.go:11:6: exported type CommentWriter should have comment or be unexported 165 $ golint ./... | reviewdog -efm="%f:%l:%c: %m" -diff="git diff FETCH_HEAD" 166 ``` 167 168 | name | description | 169 | ---- | ----------- | 170 | %f | file name | 171 | %l | line number | 172 | %c | column number | 173 | %m | error message | 174 | %% | the single '%' character | 175 | ... | ... | 176 177 Please see [reviewdog/errorformat](https://github.com/reviewdog/errorformat) 178 and [:h errorformat](https://vim-jp.org/vimdoc-en/quickfix.html#error-file-format) 179 if you want to deal with a more complex output. 'errorformat' can handle more 180 complex output like a multi-line error message. 181 182 You can also try errorformat on [the Playground](https://reviewdog.github.io/errorformat-playground/)! 183 184 By this 'errorformat' feature, reviewdog can support any tools output with ease. 185 186 ### Available pre-defined 'errorformat' 187 188 But, you don't have to write 'errorformat' in many cases. reviewdog supports 189 pre-defined errorformat for major tools. 190 191 You can find available errorformat name by `reviewdog -list` and you can use it 192 with `-f={name}`. 193 194 ```shell 195 $ reviewdog -list 196 golint linter for Go source code - https://github.com/golang/lint 197 govet Vet examines Go source code and reports suspicious problems - https://golang.org/cmd/vet/ 198 sbt the interactive build tool - http://www.scala-sbt.org/ 199 ... 200 ``` 201 202 ```shell 203 $ golint ./... | reviewdog -f=golint -diff="git diff FETCH_HEAD" 204 ``` 205 206 You can add supported pre-defined 'errorformat' by contributing to [reviewdog/errorformat](https://github.com/reviewdog/errorformat) 207 208 ### Reviewdog Diagnostic Format (RDFormat) 209 210 reviewdog supports [Reviewdog Diagnostic Format (RDFormat)](./proto/rdf/) as a 211 generic diagnostic format and it supports both [rdjson](./proto/rdf/#rdjson) and 212 [rdjsonl](./proto/rdf/#rdjsonl) formats. 213 214 This rdformat supports rich feature like multiline ranged comments, severity, 215 rule code with URL, and [code suggestions](#code-suggestions). 216 217 ```shell 218 $ <linter> | <convert-to-rdjson> | reviewdog -f=rdjson -reporter=github-pr-review 219 # or 220 $ <linter> | <convert-to-rdjsonl> | reviewdog -f=rdjsonl -reporter=github-pr-review 221 ``` 222 223 #### Example: ESLint with RDFormat 224 225 ![eslint reviewdog rdjson demo](https://user-images.githubusercontent.com/3797062/97085944-87233a80-165b-11eb-94a8-0a47d5e24905.png) 226 227 You can use [eslint-formatter-rdjson](https://www.npmjs.com/package/eslint-formatter-rdjson) 228 to output `rdjson` as eslint output format. 229 230 ```shell 231 $ npm install --save-dev eslint-formatter-rdjson 232 $ eslint -f rdjson . | reviewdog -f=rdjson -reporter=github-pr-review 233 ``` 234 235 Or you can also use [reviewdog/action-eslint](https://github.com/reviewdog/action-eslint) for GitHub Actions. 236 237 ### Diff 238 239 ![reviewdog with gofmt example](https://user-images.githubusercontent.com/3797062/89168305-a3ad5a80-d5b7-11ea-8939-be7ac1976d30.png) 240 241 reviewdog supports diff (unified format) as an input format especially useful 242 for [code suggestions](#code-suggestions). 243 reviewdog can integrate with any code suggestions tools or formatters to report suggestions. 244 245 `-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) 246 247 ```shell 248 $ <any-code-fixer/formatter> # e.g. eslint --fix, gofmt 249 $ TMPFILE=$(mktemp) 250 $ git diff >"${TMPFILE}" 251 $ git stash -u && git stash drop 252 $ reviewdog -f=diff -f.diff.strip=1 -reporter=github-pr-review < "${TMPFILE}" 253 ``` 254 255 Or you can also use [reviewdog/action-suggester](https://github.com/reviewdog/action-suggester) for GitHub Actions. 256 257 If diagnostic tools support diff output format, you can pipe the diff directly. 258 259 ```shell 260 $ gofmt -s -d . | reviewdog -name="gofmt" -f=diff -f.diff.strip=0 -reporter=github-pr-review 261 $ shellcheck -f diff $(shfmt -f .) | reviewdog -f=diff 262 ``` 263 264 ### checkstyle format 265 266 reviewdog also accepts [checkstyle XML format](http://checkstyle.sourceforge.net/) as well. 267 If the linter supports checkstyle format as a report format, you can use 268 -f=checkstyle instead of using 'errorformat'. 269 270 ```shell 271 # Local 272 $ eslint -f checkstyle . | reviewdog -f=checkstyle -diff="git diff" 273 274 # CI (overwrite tool name which is shown in review comment by -name arg) 275 $ eslint -f checkstyle . | reviewdog -f=checkstyle -name="eslint" -reporter=github-check 276 ``` 277 278 Also, if you want to pass other Json/XML/etc... format to reviewdog, you can write a converter. 279 280 ```shell 281 $ <linter> | <convert-to-checkstyle> | reviewdog -f=checkstyle -name="<linter>" -reporter=github-pr-check 282 ``` 283 284 ## Code Suggestions 285 286 ![eslint reviewdog suggestion demo](https://user-images.githubusercontent.com/3797062/97085944-87233a80-165b-11eb-94a8-0a47d5e24905.png) 287 ![reviewdog with gofmt example](https://user-images.githubusercontent.com/3797062/89168305-a3ad5a80-d5b7-11ea-8939-be7ac1976d30.png) 288 289 reviewdog supports *code suggestions* feature with [rdformat](#reviewdog-diagnostic-format-rdformat) or [diff](#diff) input. 290 You can also use [reviewdog/action-suggester](https://github.com/reviewdog/action-suggester) for GitHub Actions. 291 292 reviewdog can suggest code changes along with diagnostic results if a diagnostic tools supports code suggestions data. 293 You can integrate reviewdog with any code fixing tools and any code formatter with [diff](#diff) input as well. 294 295 ### Code Suggestions Support Table 296 Note that not all reporters provide support of code suggestion. 297 298 | `-reporter` | Suggestion support | 299 | ---------------------------- | ------- | 300 | **`local`** | NO [1] | 301 | **`github-check`** | NO [2] | 302 | **`github-pr-check`** | NO [2] | 303 | **`github-pr-review`** | OK | 304 | **`gitlab-mr-discussion`** | NO [1] | 305 | **`gitlab-mr-commit`** | NO [2] | 306 | **`gerrit-change-review`** | NO [1] | 307 | **`bitbucket-code-report`** | NO [2] | 308 309 - [1] The reporter service support code suggestion feature, but reviewdog does not support it yet. See [#678](https://github.com/friedemannf/reviewdog/issues/678) for the status. 310 - [2] The reporter service itself doesn't support code suggestion feature. 311 312 ## reviewdog config file 313 314 reviewdog can also be controlled via the .reviewdog.yml configuration file instead of "-f" or "-efm" arguments. 315 316 With .reviewdog.yml, you can run the same commands both CI service and local 317 environment including editor integration with ease. 318 319 #### .reviewdog.yml 320 321 ```yaml 322 runner: 323 <tool-name>: 324 cmd: <command> # (required) 325 errorformat: # (optional if you use `format`) 326 - <list of errorformat> 327 format: <format-name> # (optional if you use `errorformat`. e.g. golint,rdjson,rdjsonl) 328 name: <tool-name> # (optional. you can overwrite <tool-name> defined by runner key) 329 level: <level> # (optional. same as -level flag. [info,warning,error]) 330 331 # examples 332 golint: 333 cmd: golint ./... 334 errorformat: 335 - "%f:%l:%c: %m" 336 level: warning 337 govet: 338 cmd: go vet -all . 339 format: govet 340 your-awesome-linter: 341 cmd: awesome-linter run 342 format: rdjson 343 name: AwesomeLinter 344 ``` 345 346 ```shell 347 $ reviewdog -diff="git diff FETCH_HEAD" 348 project/run_test.go:61:28: [golint] error strings should not end with punctuation 349 project/run.go:57:18: [errcheck] defer os.Setenv(name, os.Getenv(name)) 350 project/run.go:58:12: [errcheck] os.Setenv(name, "") 351 # You can use -runners to run only specified runners. 352 $ reviewdog -diff="git diff FETCH_HEAD" -runners=golint,govet 353 project/run_test.go:61:28: [golint] error strings should not end with punctuation 354 # You can use -conf to specify config file path. 355 $ reviewdog -conf=./.reviewdog.yml -reporter=github-pr-check 356 ``` 357 358 Output format for project config based run is one of the following formats. 359 360 - `<file>: [<tool name>] <message>` 361 - `<file>:<lnum>: [<tool name>] <message>` 362 - `<file>:<lnum>:<col>: [<tool name>] <message>` 363 364 ## Reporters 365 366 reviewdog can report results both in local environment and review services as 367 continuous integration. 368 369 ### Reporter: Local (-reporter=local) [default] 370 371 reviewdog can find newly introduced findings by filtering linter results 372 using diff. You can pass diff command as `-diff` arg. 373 374 ```shell 375 $ golint ./... | reviewdog -f=golint -diff="git diff FETCH_HEAD" 376 ``` 377 378 ### Reporter: GitHub Checks (-reporter=github-pr-check) 379 380 [![github-pr-check sample annotation with option 1](https://user-images.githubusercontent.com/3797062/64875597-65016f80-d688-11e9-843f-4679fb666f0d.png)](https://github.com/friedemannf/reviewdog/pull/275/files#annotation_6177941961779419) 381 [![github-pr-check sample](https://user-images.githubusercontent.com/3797062/40884858-6efd82a0-6756-11e8-9f1a-c6af4f920fb0.png)](https://github.com/friedemannf/reviewdog/pull/131/checks) 382 383 github-pr-check reporter reports results to [GitHub Checks](https://help.github.com/articles/about-status-checks/). 384 385 You can change report level for this reporter by `level` field in [config 386 file](#reviewdog-config-file) or `-level` flag. You can control GitHub status 387 check result with this feature. (default: error) 388 389 | Level | GitHub Status | 390 | --------- | ------------- | 391 | `info` | neutral | 392 | `warning` | neutral | 393 | `error` | failure | 394 395 There are two options to use this reporter. 396 397 #### Option 1) Run reviewdog from GitHub Actions w/ secrets.GITHUB_TOKEN 398 399 Example: [.github/workflows/reviewdog.yml](.github/workflows/reviewdog.yml) 400 401 ```yaml 402 - name: Run reviewdog 403 env: 404 REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} 405 run: | 406 golint ./... | reviewdog -f=golint -reporter=github-pr-check 407 ``` 408 409 See [GitHub Actions](#github-actions) section too. You can also use public 410 reviewdog GitHub Actions. 411 412 #### Option 2) Install reviewdog GitHub Apps 413 reviewdog CLI send a request to reviewdog GitHub App server and the server post 414 results as GitHub Checks, because Check API only supported for GitHub App and 415 GitHub Actions. 416 417 1. Install reviewdog Apps. https://github.com/apps/reviewdog 418 2. Set `REVIEWDOG_TOKEN` or run reviewdog CLI in trusted CI providers. 419 - Get token from `https://reviewdog.app/gh/{owner}/{repo-name}`. 420 421 ```shell 422 $ export REVIEWDOG_TOKEN="<token>" 423 $ reviewdog -reporter=github-pr-check 424 ``` 425 426 Note: Token is not required if you run reviewdog in Travis or AppVeyor. 427 428 *Caution* 429 430 As described above, github-pr-check reporter with Option 2 depends on 431 reviewdog GitHub App server. 432 The server is running with haya14busa's pocket money for now and I may break 433 things, so I cannot ensure that the server is running 24h and 365 days. 434 435 **UPDATE:** Started getting support by [opencollective](https://opencollective.com/reviewdog) 436 and GitHub sponsor. 437 See [Supporting reviewdog](#supporting-reviewdog) 438 439 You can use github-pr-review reporter or use run reviewdog under GitHub Actions 440 if you don't want to depend on reviewdog server. 441 442 ### Reporter: GitHub Checks (-reporter=github-check) 443 444 It's basically same as `-reporter=github-pr-check` except it works not only for 445 Pull Request but also for commit. 446 447 [![sample comment outside diff](https://user-images.githubusercontent.com/3797062/69917921-e0680580-14ae-11ea-9a56-de9e3cbac005.png)](https://github.com/friedemannf/reviewdog/pull/364/files) 448 449 You can create [reviewdog badge](#reviewdog-badge-) for this reporter. 450 451 ### Reporter: GitHub PullRequest review comment (-reporter=github-pr-review) 452 453 [![sample-comment.png](https://raw.githubusercontent.com/haya14busa/i/dc0ccb1e110515ea407c146d99b749018db05c45/reviewdog/sample-comment.png)](https://github.com/friedemannf/reviewdog/pull/24#discussion_r84599728) 454 455 github-pr-review reporter reports results to GitHub PullRequest review comments 456 using GitHub Personal API Access Token. 457 [GitHub Enterprise](https://enterprise.github.com/home) is supported too. 458 459 - Go to https://github.com/settings/tokens and generate new API token. 460 - Check `repo` for private repositories or `public_repo` for public repositories. 461 462 ```shell 463 $ export REVIEWDOG_GITHUB_API_TOKEN="<token>" 464 $ reviewdog -reporter=github-pr-review 465 ``` 466 467 For GitHub Enterprise, set API endpoint by environment variable. 468 469 ```shell 470 $ export GITHUB_API="https://example.githubenterprise.com/api/v3/" 471 $ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL 472 ``` 473 474 See [GitHub Actions](#github-actions) section too if you can use GitHub 475 Actions. You can also use public reviewdog GitHub Actions. 476 477 ### Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion) 478 479 [![gitlab-mr-discussion sample](https://user-images.githubusercontent.com/3797062/41810718-f91bc540-773d-11e8-8598-fbc09ce9b1c7.png)](https://gitlab.com/haya14busa/reviewdog/merge_requests/113#note_83411103) 480 481 Required GitLab version: >= v10.8.0 482 483 gitlab-mr-discussion reporter reports results to GitLab MergeRequest discussions using 484 GitLab Personal API Access token. 485 Get the token with `api` scope from https://gitlab.com/profile/personal_access_tokens. 486 487 ```shell 488 $ export REVIEWDOG_GITLAB_API_TOKEN="<token>" 489 $ reviewdog -reporter=gitlab-mr-discussion 490 ``` 491 492 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. 493 494 Alternatively, `GITLAB_API` can also be defined, in which case it will take precedence over `CI_API_V4_URL`. 495 496 ```shell 497 $ export GITLAB_API="https://example.gitlab.com/api/v4" 498 $ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL 499 ``` 500 501 ### Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit) 502 503 gitlab-mr-commit is similar to [gitlab-mr-discussion](#reporter-gitlab-mergerequest-discussions--reportergitlab-mr-discussion) reporter but reports results to each commit in GitLab MergeRequest. 504 505 gitlab-mr-discussion is recommended, but you can use gitlab-mr-commit reporter 506 if your GitLab version is under v10.8.0. 507 508 ```shell 509 $ export REVIEWDOG_GITLAB_API_TOKEN="<token>" 510 $ reviewdog -reporter=gitlab-mr-commit 511 ``` 512 513 ### Reporter: Gerrit Change review (-reporter=gerrit-change-review) 514 515 gerrit-change-review reporter reports result to Gerrit Change using Gerrit Rest APIs. 516 517 The reporter supports Basic Authentication and Git-cookie based authentication for reporting results. 518 519 Set `GERRIT_USERNAME` and `GERRIT_PASSWORD` environment variables for basic authentication, and put `GIT_GITCOOKIE_PATH` for git cookie based authentication. 520 521 ```shell 522 $ export GERRIT_CHANGE_ID=changeID 523 $ export GERRIT_REVISION_ID=revisionID 524 $ export GERRIT_BRANCH=master 525 $ export GERRIT_ADDRESS=http://<gerrit-host>:<gerrit-port> 526 $ reviewdog -reporter=gerrit-change-review 527 ``` 528 529 ### Reporter: Bitbucket Code Insights Reports (-reporter=bitbucket-code-report) 530 531 [![bitbucket-code-report](https://user-images.githubusercontent.com/9948629/96770123-c138d600-13e8-11eb-8e46-250b4bb393bd.png)](https://bitbucket.org/Trane9991/reviewdog-example/pull-requests/1) 532 [![bitbucket-code-annotations](https://user-images.githubusercontent.com/9948629/97054896-5e813f00-158e-11eb-9ad7-f8d75489b8ba.png)](https://bitbucket.org/Trane9991/reviewdog-example/pull-requests/1) 533 534 bitbucket-code-report generates the annotated 535 [Bitbucket Code Insights](https://support.atlassian.com/bitbucket-cloud/docs/code-insights/) report. 536 537 For now, only the `no-filter` mode supported, so the whole project is scanned on every run. 538 Reports are stored per commit and can be viewed per commit from Bitbucket Pipelines UI or 539 in Pull Request. In the Pull Request UI affected code lines will be annotated in the diff, 540 as well as you will be able to filter the annotations by **This pull request** or **All**. 541 542 If running from [Bitbucket Pipelines](#bitbucket-pipelines), no additional configuration is needed (even credentials). 543 If running locally or from some other CI system you would need to provide Bitbucket API credentials: 544 545 - For Basic Auth you need to set following env variables: 546 `BITBUCKET_USER` and `BITBUCKET_PASSWORD` 547 - For AccessToken Auth you need to set `BITBUCKET_ACCESS_TOKEN` 548 549 ```shell 550 $ export BITBUCKET_USER="my_user" 551 $ export BITBUCKET_PASSWORD="my_password" 552 $ reviewdog -reporter=bitbucket-code-report 553 ``` 554 555 To post report to Bitbucket Server use `BITBUCKET_SERVER_URL` variable: 556 ```shell 557 $ export BITBUCKET_USER="my_user" 558 $ export BITBUCKET_PASSWORD="my_password" 559 $ export BITBUCKET_SERVER_URL="https://bitbucket.my-company.com" 560 $ reviewdog -reporter=bitbucket-code-report 561 ``` 562 563 ## Supported CI services 564 565 ### [GitHub Actions](https://github.com/features/actions) 566 567 Example: [.github/workflows/reviewdog.yml](.github/workflows/reviewdog.yml) 568 569 ```yaml 570 name: reviewdog 571 on: [pull_request] 572 jobs: 573 reviewdog: 574 name: reviewdog 575 runs-on: ubuntu-latest 576 steps: 577 # ... 578 - uses: reviewdog/action-setup@v1 579 with: 580 reviewdog_version: latest # Optional. [latest,nightly,v.X.Y.Z] 581 - name: Run reviewdog 582 env: 583 REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} 584 run: | 585 reviewdog -reporter=github-pr-check -runners=golint,govet 586 # or 587 reviewdog -reporter=github-pr-review -runners=golint,govet 588 ``` 589 590 <details> 591 <summary><strong>Example (github-check reporter):</strong></summary> 592 593 [.github/workflows/reviewdog](.github/workflows/reviewdog.yml) 594 595 Only `github-check` reporter can run on push event too. 596 597 ```yaml 598 name: reviewdog (github-check) 599 on: 600 push: 601 branches: 602 - master 603 pull_request: 604 605 jobs: 606 reviewdog: 607 name: reviewdog 608 runs-on: ubuntu-latest 609 steps: 610 # ... 611 - name: Run reviewdog 612 env: 613 REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} 614 run: | 615 reviewdog -reporter=github-check -runners=golint,govet 616 ``` 617 618 </details> 619 620 #### Public Reviewdog GitHub Actions 621 You can use public GitHub Actions to start using reviewdog with ease! :tada: :arrow_forward: :tada: 622 623 - Common 624 - [reviewdog/action-misspell](https://github.com/reviewdog/action-misspell) - Run [misspell](https://github.com/client9/misspell). 625 - Text (e.g. Markdown) 626 - [reviewdog/action-alex](https://github.com/reviewdog/action-alex) - Run [alex](https://github.com/get-alex/alex) which catches insensitive, inconsiderate writing. (e.g. master/slave) 627 - [reviewdog/action-languagetool](https://github.com/reviewdog/action-languagetool) - Run [languagetool](https://github.com/languagetool-org/languagetool). 628 - [tsuyoshicho/action-textlint](https://github.com/tsuyoshicho/action-textlint) - Run [textlint](https://github.com/textlint/textlint) 629 - [tsuyoshicho/action-redpen](https://github.com/tsuyoshicho/action-redpen) - Run [redpen](https://github.com/redpen-cc/redpen) 630 - Docker 631 - [reviewdog/action-hadolint](https://github.com/reviewdog/action-hadolint) - Run [hadolint](https://github.com/hadolint/hadolint) to lint `Dockerfile`. 632 - Env 633 - [dotenv-linter/action-dotenv-linter](https://github.com/dotenv-linter/action-dotenv-linter) - Run [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) to lint `.env` files. 634 - Shell script 635 - [reviewdog/action-shellcheck](https://github.com/reviewdog/action-shellcheck) - Run [shellcheck](https://github.com/koalaman/shellcheck). 636 - Go 637 - [reviewdog/action-staticcheck](https://github.com/reviewdog/action-staticcheck) - Run [staticcheck](https://staticcheck.io/). 638 - [reviewdog/action-golangci-lint](https://github.com/reviewdog/action-golangci-lint) - Run [golangci-lint](https://github.com/golangci/golangci-lint) and supported linters individually by golangci-lint. 639 - JavaScript 640 - [reviewdog/action-eslint](https://github.com/reviewdog/action-eslint) - Run [eslint](https://github.com/eslint/eslint). 641 - CSS 642 - [reviewdog/action-stylelint](https://github.com/reviewdog/action-stylelint) - Run [stylelint](https://github.com/stylelint/stylelint). 643 - Vim script 644 - [reviewdog/action-vint](https://github.com/reviewdog/action-vint) - Run [vint](https://github.com/Kuniwak/vint). 645 - [tsuyoshicho/action-vimlint](https://github.com/tsuyoshicho/action-vimlint) - Run [vim-vimlint](https://github.com/syngan/vim-vimlint) 646 - Terraform 647 - [reviewdog/action-tflint](https://github.com/reviewdog/action-tflint) - Run [tflint](https://github.com/wata727/tflint). 648 - YAML 649 - [reviewdog/action-yamllint](https://github.com/reviewdog/action-yamllint) - Run [yamllint](https://github.com/adrienverge/yamllint). 650 - Ruby 651 - [reviewdog/action-brakeman](https://github.com/reviewdog/action-brakeman) - Run [brakeman](https://github.com/presidentbeef/brakeman). 652 - [reviewdog/action-reek](https://github.com/reviewdog/action-reek) - Run [reek](https://github.com/troessner/reek). 653 - [reviewdog/action-rubocop](https://github.com/reviewdog/action-rubocop) - Run [rubocop](https://github.com/rubocop-hq/rubocop). 654 - [vk26/action-fasterer](https://github.com/vk26/action-fasterer) - Run [fasterer](https://github.com/DamirSvrtan/fasterer). 655 - [SennaLabs/action-standardrb](https://github.com/SennaLabs/action-standardrb) - Run [standardrb](https://github.com/testdouble/standard). 656 657 - Python 658 - [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide) - Run wemake-python-styleguide 659 - [tsuyoshicho/action-mypy](https://github.com/tsuyoshicho/action-mypy) - Run [mypy](https://pypi.org/project/mypy/) 660 - [jordemort/action-pyright](https://github.com/jordemort/action-pyright) - Run [pyright](https://github.com/Microsoft/pyright) 661 - [dciborow/action-pylint](https://github.com/dciborow/action-pylint) - Run [pyright](https://github.com/PyCQA/pylint) 662 - Kotlin 663 - [ScaCap/action-ktlint](https://github.com/ScaCap/action-ktlint) - Run [ktlint](https://ktlint.github.io/). 664 - Android Lint 665 - [dvdandroid/action-android-lint](https://github.com/DVDAndroid/action-android-lint) - Run [Android Lint](https://developer.android.com/studio/write/lint) 666 - Ansible 667 - [reviewdog/action-ansiblelint](https://github.com/reviewdog/action-ansiblelint) - Run [ansible-lint](https://github.com/ansible/ansible-lint) 668 669 ... and more on [GitHub Marketplace](https://github.com/marketplace?utf8=✓&type=actions&query=reviewdog). 670 671 Missing actions? Check out [reviewdog/action-template](https://github.com/reviewdog/action-template) and create a new reviewdog action! 672 673 Please open a Pull Request to add your created reviewdog actions here :sparkles:. 674 I can also put your repositories under reviewdog org and co-maintain the actions. 675 Example: [action-tflint](https://github.com/friedemannf/reviewdog/issues/322). 676 677 #### Graceful Degradation for Pull Requests from forked repositories 678 679 ![Graceful Degradation example](https://user-images.githubusercontent.com/3797062/71781334-e2266b00-3010-11ea-8a38-dee6e30c8162.png) 680 681 `GITHUB_TOKEN` for Pull Requests from forked repository doesn't have write 682 access to Check API nor Review API due to [GitHub Actions 683 restriction](https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#permissions-for-the-github_token). 684 685 Instead, reviewdog uses [Logging commands of GitHub 686 Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/development-tools-for-github-actions#set-an-error-message-error) 687 to post results as 688 [annotations](https://developer.github.com/v3/checks/runs/#annotations-object) 689 similar to `github-pr-check` reporter. 690 691 Note that there is a limitation for annotations created by logging commands, 692 such as [max # of annotations per run](https://github.com/friedemannf/reviewdog/issues/411#issuecomment-570893427). 693 You can check GitHub Actions log to see full results in such cases. 694 695 #### reviewdog badge [![reviewdog](https://github.com/friedemannf/reviewdog/workflows/reviewdog/badge.svg?branch=master&event=push)](https://github.com/friedemannf/reviewdog/actions?query=workflow%3Areviewdog+event%3Apush+branch%3Amaster) 696 697 As [`github-check` reporter](#reporter-github-checks--reportergithub-pr-check) support running on commit, we can create reviewdog 698 [GitHub Action badge](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/configuring-a-workflow#adding-a-workflow-status-badge-to-your-repository) 699 to check the result against master commit for example. :tada: 700 701 Example: 702 ``` 703 <!-- Replace <OWNER> and <REPOSITORY>. It assumes workflow name is "reviewdog" --> 704 [![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) 705 ``` 706 707 ### Travis CI 708 709 #### Travis CI (-reporter=github-pr-check) 710 711 If you use -reporter=github-pr-check in Travis CI, you don't need to set `REVIEWDOG_TOKEN`. 712 713 Example: 714 715 ```yaml 716 install: 717 - mkdir -p ~/bin/ && export PATH="~/bin/:$PATH" 718 - curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ~/bin 719 720 script: 721 - reviewdog -conf=.reviewdog.yml -reporter=github-pr-check 722 ``` 723 724 #### Travis CI (-reporter=github-pr-review) 725 726 Store GitHub API token by [travis encryption keys](https://docs.travis-ci.com/user/encryption-keys/). 727 728 ```shell 729 $ gem install travis 730 $ travis encrypt REVIEWDOG_GITHUB_API_TOKEN=<token> --add env.global 731 ``` 732 Example: 733 734 ```yaml 735 env: 736 global: 737 - secure: <token> 738 739 install: 740 - mkdir -p ~/bin/ && export PATH="~/bin/:$PATH" 741 - curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ~/bin 742 743 script: 744 - >- 745 golint ./... | reviewdog -f=golint -reporter=github-pr-review 746 ``` 747 748 Examples 749 - https://github.com/azu/textlint-reviewdog-example 750 751 ### Circle CI 752 753 Store `REVIEWDOG_GITHUB_API_TOKEN` (or `REVIEWDOG_TOKEN` for github-pr-check) in 754 [Environment variables - CircleCI](https://circleci.com/docs/environment-variables/#setting-environment-variables-for-all-commands-without-adding-them-to-git) 755 756 #### .circleci/config.yml sample 757 758 ```yaml 759 version: 2 760 jobs: 761 build: 762 docker: 763 - image: golang:latest 764 steps: 765 - checkout 766 - run: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s -- -b ./bin 767 - run: go vet ./... 2>&1 | ./bin/reviewdog -f=govet -reporter=github-pr-review 768 769 # Deprecated: prefer GitHub Actions to use github-pr-check reporter. 770 - run: go vet ./... 2>&1 | ./bin/reviewdog -f=govet -reporter=github-pr-check 771 ``` 772 773 ### GitLab CI 774 775 Store `REVIEWDOG_GITLAB_API_TOKEN` in [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/#variables). 776 777 #### .gitlab-ci.yml sample 778 779 ```yaml 780 reviewdog: 781 script: 782 - reviewdog -reporter=gitlab-mr-discussion 783 # Or 784 - reviewdog -reporter=gitlab-mr-commit 785 ``` 786 787 ### Bitbucket Pipelines 788 789 No additional configuration is needed. 790 791 #### bitbucket-pipelines.yml sample 792 793 ```yaml 794 pipelines: 795 default: 796 - step: 797 name: Reviewdog 798 image: golangci/golangci-lint:v1.31-alpine 799 script: 800 - wget -O - -q https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | 801 sh -s -- -b $(go env GOPATH)/bin 802 - golangci-lint run --out-format=line-number ./... | reviewdog -f=golangci-lint -reporter=bitbucket-code-report 803 ``` 804 805 ### Common (Jenkins, local, etc...) 806 807 You can use reviewdog to post review comments from anywhere with following 808 environment variables. 809 810 | name | description | 811 | ---- | ----------- | 812 | `CI_PULL_REQUEST` | Pull Request number (e.g. 14) | 813 | `CI_COMMIT` | SHA1 for the current build | 814 | `CI_REPO_OWNER` | repository owner (e.g. "haya14busa" for https://github.com/haya14busa/reviewdog) | 815 | `CI_REPO_NAME` | repository name (e.g. "reviewdog" for https://github.com/haya14busa/reviewdog) | 816 | `CI_BRANCH` | [optional] branch of the commit | 817 818 ```shell 819 $ export CI_PULL_REQUEST=14 820 $ export CI_REPO_OWNER=haya14busa 821 $ export CI_REPO_NAME=reviewdog 822 $ export CI_COMMIT=$(git rev-parse HEAD) 823 ``` 824 and set a token if required. 825 826 ```shell 827 $ REVIEWDOG_TOKEN="<token>" 828 $ REVIEWDOG_GITHUB_API_TOKEN="<token>" 829 $ REVIEWDOG_GITLAB_API_TOKEN="<token>" 830 ``` 831 832 If a CI service doesn't provide information such as Pull Request ID - reviewdog can guess it by branch name and commit SHA. 833 Just pass the flag `guess`: 834 835 ```shell 836 $ reviewdog -conf=.reviewdog.yml -reporter=github-pr-check -guess 837 ``` 838 839 #### Jenkins with Github pull request builder plugin 840 - [GitHub pull request builder plugin - Jenkins - Jenkins Wiki](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin) 841 842 ```shell 843 $ export CI_PULL_REQUEST=${ghprbPullId} 844 $ export CI_REPO_OWNER=haya14busa 845 $ export CI_REPO_NAME=reviewdog 846 $ export CI_COMMIT=${ghprbActualCommit} 847 $ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need 848 $ REVIEWDOG_TOKEN="<token>" reviewdog -reporter=github-pr-check 849 # Or 850 $ REVIEWDOG_GITHUB_API_TOKEN="<token>" reviewdog -reporter=github-pr-review 851 ``` 852 853 ## Exit codes 854 By default reviewdog will return `0` as exit code even if it finds errors. 855 If `-fail-on-error` flag is passed, reviewdog exits with `1` when at least one error was found/reported. 856 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. 857 858 See also `-level` flag for [github-pr-check/github-check](#reporter-github-checks--reportergithub-pr-check) reporters. 859 reviewdog will exit with `1` if reported check status is `failure` as well if `-fail-on-error=true`. 860 861 ## Filter mode 862 reviewdog filter results by diff and you can control how reviewdog filter results by `-filter-mode` flag. 863 Available filter modes are as below. 864 865 ### `added` (default) 866 Filter results by added/modified lines. 867 ### `diff_context` 868 Filter results by diff context. i.e. changed lines +-N lines (N=3 for example). 869 ### `file` 870 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. 871 ### `nofilter` 872 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. 873 874 `-fail-on-error` also works with any filter-mode and can catch all results from any linters with `nofilter` mode. 875 876 Example: 877 ```shell 878 $ reviewdog -reporter=github-pr-review -filter-mode=nofilter -fail-on-error 879 ``` 880 881 ### Filter Mode Support Table 882 Note that not all reporters provide full support of filter mode due to API limitation. 883 e.g. `github-pr-review` reporter uses [GitHub Review 884 API](https://developer.github.com/v3/pulls/reviews/) but it doesn't support posting comment outside diff (`diff_context`), 885 so reviewdog will use [Check annotation](https://developer.github.com/v3/checks/runs/) as fallback to post those comments [1]. 886 887 | `-reporter` \ `-filter-mode` | `added` | `diff_context` | `file` | `nofilter` | 888 | ---------------------------- | ------- | -------------- | ----------------------- | ---------- | 889 | **`local`** | OK | OK | OK | OK | 890 | **`github-check`** | OK | OK | OK | OK | 891 | **`github-pr-check`** | OK | OK | OK | OK | 892 | **`github-pr-review`** | OK | OK | Partially Supported [1] | Partially Supported [1] | 893 | **`gitlab-mr-discussion`** | OK | OK | OK | Partially Supported [2] | 894 | **`gitlab-mr-commit`** | OK | Partially Supported [2] | Partially Supported [2] | Partially Supported [2] | 895 | **`gerrit-change-review`** | OK | OK? [3] | OK? [3] | Partially Supported? [2][3] | 896 | **`bitbucket-code-report`** | NO [4] | NO [4] | NO [4] | OK | 897 898 - [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. 899 - [2] Report results which is outside diff file to console. 900 - [3] It should work, but not verified yet. 901 - [4] Not implemented at the moment 902 903 ## Debugging 904 905 Use the `-tee` flag to show debug info. 906 907 ```shell 908 reviewdog -filter-mode=nofilter -tee 909 ``` 910 911 ## Articles 912 - [reviewdog — A code review dog who keeps your codebase healthy ](https://medium.com/@haya14busa/reviewdog-a-code-review-dog-who-keeps-your-codebase-healthy-d957c471938b) 913 - [reviewdog ♡ GitHub Check — improved automated review experience](https://medium.com/@haya14busa/reviewdog-github-check-improved-automated-review-experience-58f89e0c95f3) 914 - [Automated Code Review on GitHub Actions with reviewdog for any languages/tools](https://medium.com/@haya14busa/automated-code-review-on-github-actions-with-reviewdog-for-any-languages-tools-20285e04448e) 915 - [GitHub Actions to guard your workflow](https://evrone.com/github-actions) 916 917 ## :bird: Author 918 haya14busa [![GitHub followers](https://img.shields.io/github/followers/haya14busa.svg?style=social&label=Follow)](https://github.com/haya14busa) 919 920 ## Contributors 921 922 [![Contributors](https://opencollective.com/reviewdog/contributors.svg?width=890)](https://github.com/friedemannf/reviewdog/graphs/contributors) 923 924 ### Supporting reviewdog 925 926 Become GitHub Sponsor for [each contributor](https://github.com/friedemannf/reviewdog/graphs/contributors) 927 or become a backer or sponsor from [opencollective](https://opencollective.com/reviewdog). 928 929 [![Become a backer](https://opencollective.com/reviewdog/tiers/backer.svg?avatarHeight=64)](https://opencollective.com/reviewdog#backers)