How to publish to Github Pages from Travis CI?

Question

We are compiling Doxygen docs on the travis-ci server and want to push them onto our gh-pages branch.

How do I handle the authorization for git push? Does someone have an example for using encrypted variables in travis-ci? Should I go for https authorization or for an SSH key?

Solution 1

Step-by-step example with HTTPS API Token in environment variable

Others have mentioned it, but here goes a more detailed procedure.

1. Create a separate repository for the website (optional). This will reduce the likelihood that you overwrite your main repository, and will keep output files from polluting it.

2. Get a Personal Access Token under https://github.com/settings/tokens

   Only enable "public_repo" access for public repositories, "repo" for private.

   Save the token somewhere as you can only see it once.

3. On the Travis settings for the repository https://travis-ci.org/<me>/<myrepo>/settings create an environment variable:

   GITHUB_API_KEY=<token>
   

   and make sure to mark "Display value in build log" as "Off".

   This is safe because only authorized pushes by you see such environment variables, so if a malicious user tries to make a pull request to get your string, the variable won't be there.

   Just make sure that you never, ever list your environment variables on your build!

4. Add the following to your .travis.yml:

   after_success: |
     if [ -n "$GITHUB_API_KEY" ]; then
       cd "$TRAVIS_BUILD_DIR"
       # This generates a `web` directory containing the website.
       make web
       cd web
       git init
       git checkout -b gh-pages
       git add .
       git -c user.name='travis' -c user.email='travis' commit -m init
       # Make sure to make the output quiet, or else the API token will leak!
       # This works because the API key can replace your password.
       git push -f -q https://<me>:[email protected]/<me>/<myrepo>-gh-pages gh-pages &>/dev/null
       cd "$TRAVIS_BUILD_DIR"
     fi
   

Alternative travis encrypt method

Explained in detail at: https://stackoverflow.com/a/33109519/895245

Encrypt the string GITHUB_API_KEY=<key> with the travis gem, and add it to your .travis.yml:

env:
  secure: <encrypted>

This has the advantage that it does not require using the Travis web interface, but does require using a Gem and some more copy pasting.

Solution 2

I don't know how recent it is, but Travis now have a built-in deployment option, basically add to your travis file :

deploy:
  provider: pages
  skip_cleanup: true
  local_dir: myfolder/  # or remove this line to upload from root of repo
  github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard
  on:
    branch: master

Make sure you don't have a .gitignore in the uploaded folder ; it only uploads non ignored files.

See the online official doc from travis : https://docs.travis-ci.com/user/deployment/pages/

There is no public key issue using "Repository Settings" approach, you generate a key in Github then copy paste it into secret/non visible fields of Travis.

Upload history issue : Note that each upload crushes any previously uploaded data, without preserving history.

• You can now (Nov 2017+) instead preserve history by adding a keep_history: true line

• This may be desirable as these snapshot builds can be voluminous, and they are reproducible at will anyway (simply branch your depot back from the revision you want). Pointing to such artifacts is typically pointing to a last successful build of a snapshot.

• However to trigger storage to a stable place, simply edit your travis to add flag :
  target_branch: Branch to push force to, defaults to gh-pages
  E.g target_branch : rc1.2

And run it once before setting it back to snapshot mode.

Another alternative that might be good for releases (I haven't personally tested though) is to publish to a Tag see : https://docs.travis-ci.com/user/deployment/releases/

Solution 3

The travis-ci documentation here recommends adding this to push to a git repo:

after_success:
   - chmod 600 .travis/deploy_key.pem # this key should have push access
   - ssh-add .travis/deploy_key.pem
   - git remote add deploy DEPLOY_REPO_URI_GOES_HERE
   - git push deploy

However, this is insecure as it has you store your unprotected private key in the github repository.

Instead you can add your ssh key as a encrypted environmental variable using the travis tool:

travis encrypt DEPLOY_KEY=<private ssh key with write access> --add env.matrix

Now you just need to add this line to the beginning of after_success:

cat $DEPLOY_KEY > .travis/deploy_key.pem

Please note that after_success will toggle in every build in the build matrix so if you have multiple jobs per build your code will get pushed multiple times, which won't do anything but is good to know that it is occurring.

Solution 4

Just to add another solution, I used a HTTPS token from github, encrypted it and used HTTPS for checkouts and pushes

View more solutions