Deploy a pkgdown site on Travis-CI to Github Pages

Source: R/deploy-site.R

deploy_site_github() sets up your SSH keys for deployment, builds the site with build_site(), commits the site to the gh-pages branch and then pushes the results back to GitHub. deploy_site_github() is meant only to be used by the CI system on Travis, it should not be called locally. deploy_to_branch() can be used to deploy a site directly to GitHub Pages locally. See 'Setup' for details on setting up your repository to use this.

deploy_site_github(
  pkg = ".",
  install = TRUE,
  tarball = Sys.getenv("PKG_TARBALL", ""),
  ssh_id = Sys.getenv("id_rsa", ""),
  commit_message = construct_commit_message(pkg),
  clean = FALSE,
  verbose = FALSE,
  host = "github.com",
  ...,
  repo_slug = Sys.getenv("TRAVIS_REPO_SLUG", "")
)

Arguments

pkg

Path to package.
install

Optionally, opt-out of automatic installation. This is necessary if the package you're documenting is a dependency of pkgdown
tarball

The location of the built package tarball. The default Travis configuration for R packages sets PKG_TARBALL to this path.
ssh_id

The private id to use, a base64 encoded content of the private pem file. This should not be your personal private key. Instead create a new keypair specifically for deploying the site. The easiest way is to use travis::use_travis_deploy().
commit_message

The commit message to be used for the commit.
clean

Clean all files from old site.
verbose

Print verbose output
host

The GitHub host url.
...

Additional arguments passed to build_site().
repo_slug

The user/repo slug for the repository.

Setup

For a quick setup, you can use usethis::use_pkgdown_travis(). It will help you with the following detailed steps.

  • Add the following to your .travis.yml file.

    before_cache: Rscript -e 'remotes::install_cran("pkgdown")'
deploy:
  provider: script
  script: Rscript -e 'pkgdown::deploy_site_github()'
  skip_cleanup: true

  • Then you will need to setup your deployment keys. The easiest way is to call travis::use_travis_deploy(). This will generate and push the necessary keys to your GitHub and Travis accounts. See the travis package website for more details.

  • Next, make sure that a gh-pages branch exists. The simplest way to do so is to run the following git commands locally:

    git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m 'Initial gh-pages commit'
git push origin gh-pages
git checkout master

    We recommend doing this outside of RStudio (with the project closed) as from RStudio's perspective you end up deleting all the files and then re-creating them.

  • If you're using a custom CNAME, make sure you have set the url in _pkgdown.yaml:

    url: https://pkgdown.r-lib.org