---
title: "Continuous integration"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Continuous integration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

You can configure `lintr` to run as part of continuous integration (either for a package or a general project containing R files) in order to automatically check that commits and pull requests do not deteriorate code style.

## For packages

### GitHub Actions

If your package is on GitHub, the easiest way to do this is with GitHub Actions.
The workflow configuration files use YAML syntax.
The `usethis` package has some great functionality that can help you with workflow files.
The most straightforward way to add a `lintr` workflow to your package is to use the [r-lib/actions](https://github.com/r-lib/actions/tree/master/examples)'s `lint` example.
To do this with `usethis`, you need to call

```r
usethis::use_github_action("lint")
```

This will create a workflow file called `lint.yaml` and place it in the correct location, namely in the `.github/workflows` directory of your repository.
This file configures all the steps required to run `lintr::lint_package()` on your package.

[lintr-bot](https://github.com/lintr-bot) will then add comments to the commit or pull request with the lints found and they will also be printed as
[annotations](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-status-checks#types-of-status-checks-on-github)
along side the status check on GitHub.
If you want to disable the commenting you can set the environment variable `LINTR_COMMENT_BOT=false`.
Additionally, if you want the builds to produce an error instead of just a warning, you can set the environment variable `LINTR_ERROR_ON_LINT=true`.
Note that this will kill the R process in case of a lint.

If your project is in a subdirectory and you would like to use GitHub Actions annotations, you can set
`options(lintr.github_annotation_project_dir = "path/to/project")` which will make sure that the annotations point to the correct paths.

### Travis CI

If you want to run `lintr` on [Travis-CI](https://www.travis-ci.com/), you will need to have Travis install the package first.
This can be done by adding the following line to your `.travis.yml`

``` yaml
r_github_packages:
  - r-lib/lintr
```

We recommend running `lintr::lint_package()` as an [after_success step in your build process](#non-failing-lints)]

Just like with GitHub Actions, [lintr-bot](https://github.com/lintr-bot) will then add comments to the commit or pull request with the lints found and
they will also be printed on Travis-CI.
The environment variables `LINTR_COMMENT_BOT` and `LINTR_ERROR_ON_LINT` mentioned for GitHub actions also work with Travis CI builds.

##### Non-failing Lints {#non-failing-lints}

``` yaml
after_success:
  - R CMD INSTALL $PKG_TARBALL
  - Rscript -e 'lintr::lint_package()'
```

Live example of a package using this setup:
[`hibpwned`](https://github.com/jumpingrivers/HIBPwned/blob/master/.travis.yml),
[lintr-bot commenting on a PR](https://github.com/jumpingrivers/HIBPwned/pull/30).

## For projects

You are not limited you using `lintr` for packages -- you can use it in combination with continuous integration for any other project.

### GitHub Actions

If your project is on GitHub, you could take advantage of GitHub Actions and the `usethis` functionality.
[r-lib/actions](https://github.com/r-lib/actions/tree/master/examples) includes a `lint-project` example, which you can use by calling:

``` r
usethis::use_github_action("lint-project")
```

### Super-Linter

`lintr` powers R lints for [Super-Linter](https://github.com/github/super-linter) and [MegaLinter](https://oxsecurity.github.io/megalinter/latest/),
which provide a unified linting experience across many languages.
Specifically, they execute `lintr::lint()` on the R and R Markdown files included in a given project.
