Auto-publishing the Yawg site

1. Introduction

This document describes the setup and tools for auto-publishing of the Yawg site. We this we achieve "continous publishing" for the Yawg site.

The Yawg site is hosted through the GitHub Pages service provided by GitHub.

To publish new content the changes must be commited to the gh-pages branch of the project. And then pushed to GitHub.

The continuous integration build jobs are under the control of Travis CI.

We created a tool to perform the actions for publishing the Yawg site. This tool will be invoked in the build job run by Travis CI.

The Yawg version to be used for baking the Yawg site will be a previously released version.

The bake and publishing will only occur for merges into the mainline. This means only commits into the master branch will trigger the auto-publishing. Commits into feature branches and pull-requests will not trigger the auto-publishing.

To ensure the auto-publishing is performed in the right context, it is important to strictly follow the workflow convention that the mainline branch (i.e. the master branch) only receives merges from feature branches.

2. Steps in the auto-publishing procedure run within Travis CI

If the build is not for a merge into the mainline, then there are no more actions to perform.
If there are no changes in the current commit related with the site (i.e. changes below doc) then there are no more actions to perform.
Prepare the SSH key for access to GitHub (cf. https://docs.travis-ci.com/user/deployment/custom/#Git).
Download and install the desired version of Yawg for baking the site. The exact version to be used is a configuration parameter.
Create a workspace with the contents of the gh-branch.
Bake the Yawg site.
Commit and push the changes to GitHub, still in the gh-branch.

3. Implementation steps

Update build-bundle to place the .tar.gz and the code quality reports into a target folder. This is because we want the publishing related tools to also have their working directories under target. The name target is chosen to follow Maven conventions. OPTIONAL
Update build-site to use target/site as the target directory for the baked site. This will also be the directory with the working area for the gh-pages branch. DONE
Update build-site to use a configured version of Yawg. This involves downloading and installing it. The Yawg installation should be placed under target/tools. DONE
Created new tool devtools/bin/build-travisci-publish-site To perform the actions specific to Travis CI. This new build-travisci-publish-site tool will in turn call build-site to perform most of the work.

4. Travis CI configuration:

cache:
  directories:
    - $HOME/.yawgdevtools

before_deploy:
  - eval "$(ssh-agent -s)"
  - openssl aes-256-cbc -K $encrypted_9f5a14dc3874_key -iv $encrypted_9f5a14dc3874_iv -in ./devtools/conf/id_rsa-travisci.enc -out ./devtools/conf/id_rsa-travisci -d
  - chmod 600 ./devtools/conf/id_rsa-travisci
  - ssh-add ./devtools/conf/id_rsa-travisci

deploy:
  skip_cleanup: true
  on:
    branch: master
  provider: script
  script: ./devtools/bin/build-site --yawg-install-root=$HOME/.yawgdevtools --upload

5. Preparing the SSH key for deploying on GitHub

This section describes how to prepare the SSH key and other files for deploying the Yawg site to GitHub from within a Travis CI job.

Install Travis CI command line client:

Debian family distributions:

apt-get install ruby-dev
gem install travis

CentOS family distributions:

yum install ruby-devel rubygems
gem install travis

Generate the SSH key for uploading the site to GitHub:

ssh-keygen \
    -t rsa \
    -N '' \
    -C 'yawg-site-upload@travisci' \
    -f ~/.ssh/id_rsa-travisci

The above command will generate two files:

~/.ssh/id_rsa-travisci
~/.ssh/id_rsa-travisci.pub

travis login --org
travis encrypt-file \
    ~/.ssh/id_rsa-travisci \
    ./devtools/conf/id_rsa-travisci.enc \
    --repo jorgefranconunes/yawg

The travis encrypt-file command will output the command that is to be used for decripting the file. That command must be added to the .travis.yml file.

6. Define new SSH key in GitHub account

Login to your GitHub account
Go to "Settings" → "SSH and and GPG keys" (settings/keys).
Click 'New SSH key'.
Paste into the form the contents of the ~/.ssh/id_rsa-travisci.pub file you created in a previous step.
And it’s done.

7. Tools

devtools/bin/build-site — Bakes the site and uploads it to the gh-pages branch of the project Github Git repository.