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

First, take special note of the proviso in `?executing_linters` about the need to have your package and its dependencies installed or loaded (e.g. with `pkgload::load_all()`) in order for certain linters (e.g. `object_usage_linter()`) to function as intended.

### 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/)'s [`lint` example](https://github.com/r-lib/actions/tree/v2-branch/examples#lint-workflow).
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.

Alternatively you can use the eponymous [`lint-changed-files.yaml`](https://github.com/r-lib/actions/blob/v2-branch/examples/lint-changed-files.yaml) to only lint any changed files:

```r
usethis::use_github_action("lint-changed-files")
```

Comments to the commit or pull request will 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 the builds to produce an error instead of just a warning, you can set the environment variable `LINTR_ERROR_ON_LINT=true`.
This is set by default for both [r-lib/actions](https://github.com/r-lib/actions/)'s `lint.yaml` and `lint-changed-files.yaml`. 
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:

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

If lints are found in the commit or pull request they will be printed on Travis-CI.
The environment variable `LINTR_ERROR_ON_LINT` mentioned for GitHub actions also works with Travis CI builds.

## For projects

You are not limited to 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/) includes a [`lint-project` example](https://github.com/r-lib/actions/tree/v2-branch/examples#lint-project-workflow), 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://megalinter.io/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.
