Walkthrough: deploy a pkgdown site from Travis

Pkgdown deploy from Travis.md

Run usethis::use_pkgdown_travis()

❯ usethis::use_pkgdown_travis()
✔ Setting active project to '/Users/gaborcsardi/works/ps'
✔ Adding 'docs/' to '.gitignore'
● Set up deploy keys by running `travis::use_travis_deploy()`
● Insert the following code in '.travis.yml'
  before_cache: Rscript -e 'remotes::install_cran("pkgdown")'
  deploy:
    provider: script
    script: Rscript -e 'pkgdown::deploy_site_github()'
    skip_cleanup: true
  [Copied to clipboard]

This adds /docs to .gitignore and tells you two other steps you need to do. Our setup here is a bit more complicated, but this is a good start.

Set up the .travis.yml file

The suggested config will probably work, but I want to use a custom pkgdown branch, and also deploy for git tags. I tend to use this config:

matrix:
  include:
    - r: 3.2
    - r: 3.3
    - r: 3.4
    - r: 3.5
    - r: release
      env: R_CODECOV=true
      before_cache: Rscript -e 'remotes::install_github("r-lib/pkgdown@fix/examples-dontshow")'
      deploy:
        provider: script
        script: Rscript -e 'pkgdown::deploy_site_github()'
        skip_cleanup: true
        on:
          all_branches: true
          condition: '"$TRAVIS_BRANCH" == "pkgdown-travis" || -n "$TRAVIS_TAG"'
    - r: devel
    - os: osx
      osx_image: xcode9.3 #High Sierra
    - os: osx
      osx_image: xcode8.3 #Sierra

We want to deploy the dev version on every push to GitHub, and also the released versions that correspond to tags. The condition line above makes sure that we deploy from the selected branch, and also for tags.

Initially you might want to set the branch (like pkgdown-travis here), to deploy from to a different one, so you don't need to experiment in the master branch. Once it is working, you can change it to master.

You probably do not need this custom pkgdown version, and you are fine with 'remotes::install_cran("pkgdown") as usethis suggested above.

Only the r: release build is interesting for pkgdown, you don't need to add the other R versions and OSes.

Setting up the _pkgdown.yml file

Make sure you have

destination: docs

development:
  mode: auto

in _pkgdown.yml. Other destination and development entries should be removed, if you had a different setup before.

Setting up deployment on Travis

This is supposed to be simple via travis::use_travis_deploy() (the travis package is at https://github.com/ropenscilabs/travis). But that has never worked for me, I am not sure why. We can follow its code manually, though, and run, from R:

key <- openssl::rsa_keygen()
pub_key <- travis:::get_public_key(key)
private_key <- travis:::encode_private_key(key)

Now go to the 'Settings' Travis page of your repo (e.g. https://travis-ci.org/r-lib/ps/settings) and add the string in private_key as an environment variable, for all branches. Its name should be id_rsa. Do not display its value in the logs. We'll need this private key a bit later, so save it now.

Now go to the GitHub repo of the package to set up the deploy key there. E.g. at https://github.com/r-lib/ps/settings/keys Click on 'Add deploy key', the title can be 'pkgdown from Travis' and the key should be the output of

openssl::write_ssh(pub_key)

Make sure you allow write access.

Trying to deploy

Now remove the /docs directory from your repo. I suggest you create a new branch, e.g. pkgdown-travis. Make sure that you configure deployment for this branch in .travis.yml, see the example Travis yaml above. Then push all changes to GitHub.

Travis will start building the new branch. You can cancel all but one builds in the build matrix, just keep the R-release one, that'll do the deployment.

If everything is OK, Travis deploys the pkgdown site for the dev version of the package. You can look at the files in the gh-pages branch, e.g. for the ps package this is at https://github.com/r-lib/ps/tree/gh-pages You should see a dev directory and in it the pkgdown website.

Deploying the released version

We still need to deploy the released version. There are various ways to do this, maybe the easiest is to do it from your computer, as you cannot go back in time and change the Travis config of the package at the time of the last release. (Alternatively, you could create a git branch from the last release tag and update the Travis and pkgdown config there, and then let Travis build your pkgdown web site.)

Check out the tag of the latest release from git, e.g. for ps:

git tag
git checkout v1.3.0

Then (temporarily) update the _pkgdown.yml file, to keep the dev version in /dev and deploy the released version in /. As above, add:

destination: docs

development:
  mode: auto

We'll deploy using pkgdown::deploy_site_github(), and this needs a tarball of the package, so let's build that first, from R:

devtools::build()

We'll also need the private key for the deployment, in the id_rsa environment variable:

Sys.setenv(id_rsa = private_key)

Ready to deploy. You'll need to provide the repo slug as well, this is detected on Travis, but not here. E.g.

pkgdown::deploy_site_github(
  tarball = "../ps_1.3.0.tar.gz",
  repo_slug = "r-lib/ps"
)

Now look at the gh-pages branch on GitHub, to make sure that it has both the released and the dev version of the package. E.g. at https://github.com/r-lib/ps/tree/gh-pages

You should see a bunch of files and directories, and again the similar structure in the dev directory.

Now you can go to the setting page of the repo, e.g. https://github.com/r-lib/ps/settings and set GitHub Pages to the gh-pages branch.

Double check that the web site is properly deployed. E.g. for the ps package, the released version is at https://ps.r-lib.org/ and the dev version it is at https://ps.r-lib.org/dev/

Cleanup and merge to master

Now clean up the changes we made in the detached HEAD of the git repo, and go back to our deployment branch:

git checkout -- .
git checkout pkgdown-travis

Update the Travis config to deploy from the master branch, like this, (see full config above):

        on:
          all_branches: true
          condition: '"$TRAVIS_BRANCH" == "master" || -n "$TRAVIS_TAG"'

You can remove the all_branches line if you like. I prefer to keep it, just in case I want to deploy from another branch in the future. I would probably forget to add it back then.

Push the pkgdown-travis branch to GitHub, create a pull request for it and merge it. Once it is merged, Travis should deploy the dev version of the pkgdown site again.

Thank you very much for this, it is very useful. The only thing is that, after a while, I ran into the following issue:

Running git push --force origin 'HEAD:gh-pages'
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/inSileco/inSilecoMisc.git/'

Error: System command 'git' failed, exit status: 128, stdout & stderr were printed

As I was not sure why I got this, I decided to go with a personal access token instead. Below is what I am currently using:

deploy:
  provider: pages
  skip_cleanup: true
  keep_history: true
  github_token: $GITHUB_TOKEN
  on:
    branch: master
  local_dir: docs

This suits my needs!

Again, thank you very much for sharing this!