Deploying Docs on Github with Travis-CI

It is very common to deploy docs from a Github repo to a Github Pages site. In the past few days, I have setup several repos that will push to Github Pages using the Travis-CI continuous integration, and I wanted to document how easy it is here.

Update

Since I have written this blog post, a commenter pointed out that Travis-CI has built-in support for deploying to github pages. In fact, the final .travis.yml file could be:

language: python
install:
- pip install mkdocs
script:
- mkdocs build --verbose --clean --strict
deploy:
 provider: pages
 skip_cleanup: true
 github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard
 local_dir: site
 on:
   branch: master

There is a trade-off with this method though. Using the built-in travis-ci method utilizes your personal GITHUB_TOKEN, which has access to all of the repositories that you have access to. By using a deploy key, as described below, it is a key specific to the single repository. Therefore, the above method is easier to setup, but could expose your GITHUB_TOKEN which has access all of your repos.

Create Deploy Key

After the repo is created, the first step is to create a deploy key.

ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-key

Do not enter a password during the key generation. We will encrypt the deploy-key with travis next.

Add the deploy-key.pub contents to to your repo’s settings under Settings -> Deploy Keys. Be sure to check the “Allow write access”. The deploy key will be used to authenticate the travis-ci build in order to push the website.

We will next have to encrypt the deploy-key so we can commit it to our repository safely.

Encrypt Deploy-key

First, you will need to install the travis command line tools, which is a Ruby Gem. After installing ruby, you can run the command:

gem install travis

Next, you will need to enable the repo to be build on Travis-CI. Log into Travis-CI and go to “Account”. Within this menu, search for the name of your repo, and click to enable it.

You will also need to login with the Travis CLI in order to encrypt the deploy-key:

travis login

Inside the repository’s git repo on your own computer, run the command:

travis encrypt-file deploy-key
...    
openssl aes-256-cbc -K $encrypted_1d262b48bc9b_key -iv $encrypted_1d262b48bc9b_iv -in deploy-key.enc -out deploy-key -d

This will encrypt the deploy-key with the Travis-CI public key, therefore it can only be accessed on the Travis-CI infrastructure. The above line is very important to remember, you will copy / paste it into the .travis.yml.

Configure Travis-CI

For most of my Travis-CI configurations, I copy from my previous configurations. Travis-CI is configured in a specially named file in your repo named .travis.yml. Here is an example configuration that builds MkDocs documentation.

env:
  global:
  - GIT_NAME: "'Markdown autodeploy'"
  - GIT_EMAIL: [email protected]
  - GH_REF: [email protected]:opensciencegrid/security.git
language: python
before_script:
- pip install mkdocs
- pip install MarkdownHighlight
script:
- openssl aes-256-cbc -K $encrypted_1d262b48bc9b_key -iv $encrypted_1d262b48bc9b_iv -in deploy-key.enc -out deploy-key -d
- chmod 600 deploy-key
- eval `ssh-agent -s`
- ssh-add deploy-key
- git config user.name "Automatic Publish"
- git config user.email "[email protected]"
- git remote add gh-token "${GH_REF}";
- git fetch gh-token && git fetch gh-token gh-pages:gh-pages;
- if [ "${TRAVIS_PULL_REQUEST}" = "false" ]; then echo "Pushing to github"; PYTHONPATH=src/ mkdocs gh-deploy -v --clean --remote-name gh-token; git push gh-token gh-pages; fi;

You can see that the openssl command that was printed while encrypting is in the script section. Be sure to copy / paste it completely into your .travis.yml file.

This file instructs Travis-CI to:

1. Install mkdocs
2. Decrypt the deploy-key
3. Builds the mkdocs documentation.
4. Push the docs to the gh-pages branch of the repo.

Commit and be prosperous

Commit the travis.yml, the deploy-key.enc. Be sure not to commit the deploy-key. And everything should be good to go!

The above examples where from the OSG Security docs repo.