---
title: "Continuous Integration"
author: "Jonathan Sidi"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette: 
    keep_md: true
vignette: >
  %\VignetteIndexEntry{Continuous Integration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Travis

### Direct

`covrpage` can be deployed in Travis much the way [covr::covralls](https://covr.r-lib.org/reference/coveralls.html) is deployed. The only difference is that `covrpage` will push back the updated `README.md` file to the originating repository so it can be updated as part of the custom integration routine. 

The following `.travis.yml` is needed for the deployment:

```yml
language: R
sudo: false
cache: packages

after_success:
- Rscript -e 'covr::codecov()'
- bash .travis/covrpage.sh

after_failure:
- bash .travis/covrpage.sh

r_github_packages: metrumresearchgroup/covrpage
env:
  global:
    secure: [Travis encrypted Github PAT]

```

covrpage adds one new line to the standard `{covr}` Travis YML:

```yml
- bash .travis/covrpage.sh
```

This file is created when running `covrpage::use_covrpage()` in the `.travis` subdirectory:

```yml
env:
  global:
    secure: IeWrPb9tC9oxkoceXs4NStZJFIJKtvi/qeErbv3OATeo+BylRwj9xzcmzQrV8ps...
```

The bash script can be run on a successful or failed build creating the covrpage report. 

To allow Travis push back into the originating repository, you will need to give it permission to do so by providing an encrypted [GitHub Personal Access Token](https://github.com/settings/tokens) (PAT). This is done using the Travis command line [function](https://docs.travis-ci.com/user/encryption-keys/).

By default, the function assumes you have defined a system environment variable `GITHUB_PAT` and will use it to define a [Travis environment variable](https://docs.travis-ci.com/user/environment-variables/) as `GH_PAT`.

  - `R` Environment Variable

To define the Github PAT as an R environment variable:

```r
Sys.setenv(GITHUB_PAT='PAT FROM GITHUB')
```

  - Travis Environment Variable

Run the following line in the terminal when you are in the root project directory (where the `.git` folder in located), the output should be appended directly to the `.travis.yml` file. Each time you run it a new `secure` line is added to the yml.

```r
travis encrypt GH_PAT="[PAT FROM GITHUB]" --add
```

These two commands are combined into a utility function:

```r
covrpage::tencrypt(r_obj = Sys.getenv("GITHUB_PAT"),travis_env = "GH_PAT",add = TRUE)
```


### Deploy + pkgdown

You can also use [pkgdown](https://www.github.com/r-lib/pkgdown) to create a covrpage readme with Travis. This is relevant or successful builds only, since travis will not invoke a deploy on a failed build.

```yml
language: r
cache: packages

after_success:
- Rscript -e 'covr::codecov()'
- Rscript -e 'devtools::install(); covrpage::covrpage_ci()'
- Rscript -e 'pkgdown::build_site()'

r_github_packages: 
  - metrumresearchgroup/covrpage
  - r-lib/pkgdown #either put this here or in Suggests in the DESCRIPTION file

deploy:
  provider: pages
  skip-cleanup: true
  github-token: "$GH_PAT"
  keep-history: true
  local-dir: docs
  on:
    branch: master

env:
  global:
    secure: [Travis encrypted Github PAT]
```

### tic
You can use the [tic](https://github.com/ropenscilabs/tic) package to manage the steps taken in travis. It is simplest to install `tic` via the [travis](https://github.com/ropenscilabs/travis) package with the function [travis::use_tic()](https://ropenscilabs.github.io/travis/reference/use_tic.html). This will take you through all the steps needed to set up the workflow in travis and github with the project repository. 

After running this function you can run [covrpage::use_covrpage(travis_type='tic')](https://metrumresearchgroup.github.io/covrpage/reference/use_covrpage.html) to copy into the project root directory the two files needed to run covrpage on travis: `tic.R` and `.travis.yml`. They can always be found in the system folder of the package.

#### Highlights

Some things to highlight in the setup of the templates. 

If the `commit` is pushed to `origin/master` then after a successful build covrpage is run and the resulting `tests/README.md` is deployed back into the `origin/master` and if there is a vignette output [pkgdown](https://www.github.com/r-lib/pkgdown) will rebuild the `docs` folder and will be deployed into `gh-pages`.

If the commit is **not** pushed to `origin/master`, ie a `origin/<branch>`, then after a successful build `covrpage` is run and the resulting `tests/README.md` is deployed back into the `origin/<branch>`.

Again, if there is an unsuccessful build on travis, then no deployment will occur. In this case you would need to use the [bash](#direct) option to deploy back into the `origin`.

#### tic.R

`system.file('templates/tic/tic.R',package = 'covrpage')`

```{r,comment=' ',echo=FALSE}
cat(readLines(system.file('templates/tic/tic.R',package = 'covrpage')),sep='\n')
```

#### tic_travis.yml

`system.file('templates/tic/tic_travis.yml',package = 'covrpage')`

```{r,comment=' ',echo=FALSE}
cat(readLines(system.file('templates/tic/tic_travis.yml',package = 'covrpage')),sep='\n')
```