Continuous Integration

Travis

Direct

covrpage can be deployed in Travis much the way covr::covralls 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:

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:

- bash .travis/covrpage.sh

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

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 (PAT). This is done using the Travis command line function.

By default, the function assumes you have defined a system environment variable GITHUB_PAT and will use it to define a Travis environment variable as GH_PAT.

R Environment Variable

To define the Github PAT as an R environment variable:

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.

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

These two commands are combined into a utility function:

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

Deploy + pkgdown

You can also use 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.

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 package to manage the steps taken in travis. It is simplest to install tic via the travis package with the function travis::use_tic(). 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’) 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 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 option to deploy back into the origin.

tic.R

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

  add_package_checks()
  
  if (Sys.getenv("id_rsa") != "") {
    # pkgdown documentation can be built optionally. Other example criteria:
    # - `inherits(ci(), "TravisCI")`: Only for Travis CI
    # - `ci()$is_tag()`: Only for tags, not for branches
    # - `Sys.getenv("BUILD_PKGDOWN") != ""`: If the env var "BUILD_PKGDOWN" is set
    # - `Sys.getenv("TRAVIS_EVENT_TYPE") == "cron"`: Only for Travis cron jobs
    get_stage("before_deploy") %>%
      add_step(step_setup_ssh())
    
    if (ci()$get_branch() == "master") {
      get_stage("deploy") %>%
        add_code_step(covr::codecov()) %>%
        add_code_step(devtools::install()) %>%
        add_code_step(covrpage::covrpage_ci()) %>%
        add_step(step_push_deploy(commit_paths = "tests/README.md")) %>%
        add_step(step_build_pkgdown()) %>%
        add_step(step_push_deploy(path = "docs", branch = "gh-pages"))
    }else{
      get_stage("deploy") %>%
        add_code_step(covr::codecov()) %>%
        add_code_step(devtools::install()) %>%
        add_code_step(covrpage::covrpage_ci()) %>%
        add_step(step_push_deploy(commit_paths = "tests/README.md"))
    }
  }

tic_travis.yml

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

  # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
  # Default configuration for use with tic package
  # Usually you shouldn't need to change the first part of the file
  
  # Header
  language: r
  cache: packages
  r_github_packages:
  - yonicd/covrpage
  - r-lib/pkgdown
  os:
  - linux
  
  #env
  env:
    global:
      - _R_CHECK_FORCE_SUGGESTS_=false
      - MAKEFLAGS="-j 2"
      
  # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
  # Default configuration for use with tic package
  # Usually you shouldn't need to change the first part of the file
  
  # DO NOT CHANGE THE CODE BELOW
  before_install: R -q -e 'install.packages(c("remotes", "curl")); remotes::install_github("ropenscilabs/tic"); tic::prepare_all_stages(); tic::before_install()'
  install: R -q -e 'tic::install()'
  after_install: R -q -e 'tic::after_install()'
  before_script: R -q -e 'tic::before_script()'
  script: R -q -e 'tic::script()'
  after_success: R -q -e 'tic::after_success()'
  after_failure: R -q -e 'tic::after_failure()'
  before_deploy: R -q -e 'tic::before_deploy()'
  deploy:
    provider: script
    script: R -q -e 'tic::deploy()'
    on:
      all_branches: true
  after_deploy: R -q -e 'tic::after_deploy()'
  after_script: R -q -e 'tic::after_script()'
  # DO NOT CHANGE THE CODE ABOVE

- Travis