Tutorial: Using Rperform with Travis CI

In this tutorial, we will use a dummy package to understand how Rperform can be integrated with Travis CI.

Note: Consider going through the tutorial, Using Rperform with packages, before this one. In case you are new to Travis CI, go through their Getting Strarted page and other introductory docs.

---

Generate an encrypted access token:

You will need to generate an access token that will be used to allow you to push a webpage containing Rperform's results to your GitHub repo's gh-page branch. This will be some really long alphanumeric string. You can generate one by going to settings -> personal access tokens -> generate new token. Since we are working with a public repo, selecting only the public_repo option under scope would do.

You will also need to install the travis ruby framework.

gem install travis

After installing, navigate to your git repo for the project you want to enable automatic pushing of content for, and then login to travis-ci and secure the GitHub token.

travis login
travis encrypt GH_TOKEN="yourgithubtoken"

This will generate output that should be copied to your .travis.yml file in a subsequent step. We will refer to this output as yoursecurestring. Essentially we have created an environment variable GH_TOKEN with your actual GitHub token, that is encrypted on the travis-ci servers. So this way you don't expose your actual GitHub token to anyone who looks at your .travis.yml file.

---

Setup:

• Fork the dummy package, RperformTestPackage, from here.

• Clone the forked repository on to on your local machine.

• Create and checkout into an orphan gh-pages branch in the RperformTestPackage directory.

cd RperformTestPackage
git checkout --orphan gh-pages
git rm -rf .

• Make an Rperform directory and create an empty index.html file inside it.

mkdir Rperform
touch Rperform/index.html

• Commit and push the changes. Then, checkout into the master branch.

git add Rperform/index.html
git commit -m "First commit"
git push origin gh-pages
git checkout master

---

Updating the .travis.yml file:

• For a sample .travis.yml file configured to work with Rperform, look here. We will use this sample file as our reference.

• Add the package names given under r_packages and r_github_packages in the sample file to your .travis.yml file under the respective sections.

r_packages:
  - microbenchmark
  - roxygen2
  - rmarkdown

r_github_packages:
  - analyticalmonk/Rperform

• Add the command given under before_script in the sample file to your .travis.yml file.

before_script:
- travis_wait 30 source `Rscript -e "cat(find.package(\"Rperform\"))"`/push_gh_pages.sh

• Next, we need to configure our environment variables.

env:
  global:
  - secure: "ENTER_YOUR_ENCRYPTED_GITHUB_ACCESS_TOKEN_HERE"
  - USER_EMAIL="INSERT_A_VALID_EMAIL_ID_HERE"
  - USER_NAME="INSERT_USERNAME_HERE"
  - PR_COMMAND="Rperform::plot_PR_webpage('./INSERT_PATH_TO_TEST_DIR/INSERT_TEST_NAME_HERE', metric = 'time')"
  - RPERFORM_COMMAND="Rperform::plot_webpage(test_directory = './INSERT_PATH_TO_TEST_DIR/', metric = 'time')"

Your encrypted_github_access_token is nothing but the yoursecurestring generated at the beginning of this tutorial.
USER_EMAIL and USER_NAME aren't required but put them in anyway if you want.
RPERFORM_COMMAND and PR_COMMAND are the Rperform commands run when a regular build and Pull Request build are triggered respectively. We will focus on regular builds. More on PR builds in another tutorial.

When configured for RperformTestPackage, these environment variables will look something like this:

env:
  global:
  - secure: "yoursecurestring"
  - USER_EMAIL="analyticalmonk@github.com"
  - USER_NAME="analyticalmonk"
  - RPERFORM_COMMAND="Rperform::plot_webpage(test_directory = './tests/testthat', metric = 'time')"

• Add and commit the changes.

git add .
git commit -m "Configured Travis CI to run Rperform"

Trigger an Rperform-integrated Travis build:

• Before pushing the changes, go to your Travis profile page and make sure that you have enabled Travis CI for RperformTestPackage repository.

• Push the changes.

git push origin master

• Once the Travis build gets completed, the required performance plots for files in the directory provided to RPERFORM_COMMAND should get generated at username.github.io/RperformTestPackage/Rperform.

---