Github Pages and Travis auto Deployment

Auto Deployment of Pyreverse output to Github Pages!

That's our today's goal - to achieve it there is a lot of middle steps to take-over.

I've found a best tutorial I could - Automatically Update Github Pages with Travis

I've follow it with successful auto-updating github page.

Ofcourse I've tweaked it to my preferences and behaviour I wanted it to be doing - generate pyreverse and push it to gh-pages.

Prerequisites

Github Pages is a Github place for keeping project's documentation . It's supports Jekyll (Ruby-Based) static page generator - in addition to regular HTML content.

Pyreverse will generate png files with class-structure and package-structure(lined), we will add this to gh-pages of our project as a Jekyll markdown md file.

How to setup your own auto-generator.

Following steps are almost identical with those presented in tutorial at the beginning of the post.

1. You need to configure source of gh-pages for your github repository

That can be done within "Github Pages" section of repository settings. Template to link with settings is below:

https://github.com/{NAME_OF_USER}/{NAME_OF_REPOSITORY}/settings/

There at the Source you have drop-down list from which you can select your branch.

Be-aware - gh-pages branch is not created by default, by default master branch is used. You will need to create it manually as I did.

2. Create Github Token for travis to use it.

Generate token at THIS PAGE - You will need to re-authorize yourself again for this page.

You add name of your token and set scope for the token - I've used only for REPO - to not overuse this token in other situations, and be sure that only repositories can be harmed if it will be compromized.

Save your generated token - it will only be visible NOW

3. Setting up Travis

Once you've saved your token, you'll need it to generate secure-token for your .travis.yml configuration file.

For this part I needed to use ruby-based docker image - but this time taking into account time-pressure, I've used x64 bit for spending less time (not that I didn't tried first building x32 image for ruby ... but that's for another post).

Ruby image with docker has a gem installer that will help us install travis commandliner that we need to create secure tokens.

In image (or if you have already installled ruby with gem) :

gem install travis

That's it - super easy. Now use travis command - best to use in your project source-code that have already .travis.yml file - cause it will change the file adding secure-token to it automatically:

 travis encrypt -r username/reponame GH_TOKEN=[the token you created before] --add

4. Now let's make a bash script that will generate and deploy to gh-pages.

Here I've more-then-less used code presented in tutorial at beginning of post. Here is how it looks like now:

#!/bin/bash
rev=$(git rev-parse --short HEAD)

if [ "$TRAVIS_BRANCH" != "master" ]
then
    echo "This commit was made against the $TRAVIS_BRANCH and not the master! No deploy!"
    exit 0
fi

mkdir -p deployed_gh_pages/${rev}
cd deployed_gh_pages/${rev}

git init
git config user.name "Anselmos"
git config user.email "Github.com/Anselmos"

git remote add upstream "https://$GH_TOKEN@github.com/anselmos/Biking-Endorphines.git"
git fetch upstream
git reset upstream/gh-pages

cp ../../generated_pyreverse/* .  # you put here your files from whatever place you generated before this script

git add -A . # this will add all your files to staging mode
git commit -m "rebuild pages at ${rev}"  # this will commit all the files put in stage mode with information about commit-id - That's what I also wanted :) - you can track which commit made pyreverse
git push -q upstream HEAD:gh-pages  # push to github gh-pages branch.

Final results:

Each time new push to master will be done, travis will not only check as usually pylint/unit-test, but also will create pyrevesed output that is automatically moved to gh-page seen here:

Pyreverse Generated GH Page per each master push

Code commits done for this post:

Tools and applications used:

  • vi/vim
  • ruby gem installer
  • travis commandliner
  • Docker
  • pyreverse

LL (Lessons Learned)

1. Using separated branch for testing on travis - goes with error.

At first travis used separated branch and worked properly. When I've setup Github Pages at projects account Travis probably found that project is using GH-Pages and stopped all tasks on this branch.

When I've done second attempt to push to branch called pyreverse-to-gh-pages it didn't even start.

Then I was a little bit worried, what happen. I've started my research to find out why travis didn't even start to build the branch.

On the "menu options" at travis-ci page I've found "requests" page where I could see if request to start job on travis is actually working.

There I've found this beautiful error that at first glance meant nothing to me:

Github Pages branch not included via configuration

Then I've started to check if there is any type of error in my .travis.yml file as it was before by trying to add secure-tokens. But no luck with that.

Solution:

I've finally found out that Travis will revoke any branches that contains "gh-pages" name by default(at least that's my thinking about it). Check information here Safelisting or blocklisting branches - to overcome this issue I've changed .travis.yml settings and add following:

branches:
  only:
      - gh-pages
      - /.*/

That seem to made a trick.

2. Forgot about dependencies used when pyreverse generates outputs.

Pyreverse for proper usage needs "Graphviz" installed at system level. Since it's a system dependency, it's not included at requirements.txt level.

Solution:

Add installation of Graphviz at travis configuration.

Acknowledgements

Auto-deploying built products to gh-pages with Travis

Using Github Pages to host your website

Update Github Pages with Travis tutorial

What's next

1. I'll finally start coding on GPX File reader - see at Issue #7

2. Check my TODO-LIST/Issues at Github

Comments

comments powered by Disqus