demo-travis-gh-pages Build Status

Use Grunt and Travis-CI to publish content to github-pages

Note If you have any questions or feedback then feel free to leave a ticket.

Intro

This guide describes a minimal setup to enable Travis-CI to build your static website using Grunt and publish it to gh-pages branch after you push your sources to your Github repository. Using this you can automatically export the documentation for your project or publish any other static site you build with Grunt.

Every push or merge to the specified branch will trigger the Github webhooks. Travis will then clone the repository, install the dependencies and run a command. In this case we use Grunt to rebuild our site and push the site back to to your repository's gh-pages branch. This is a simple form of continuous deployment.

In this demo we depends on grunt-gh-pages and an encrypted OAuth token to enable Travis to push to a repository on your behalf.

Alternatives

If you have a project that doesn't use github-pages but instead use old-skool FTP or some other deployment method, then you replace the gh-pages task with a Grunt plugin that handles your scenario. You skip the Github OAuth token and encrypt the credentials needed for the plugin of your choice.

This example uses Grunt but most of the information is valid for other task-runners, except you'd need to find a plugin that can use an OAuth token to push content to Github.

The data you push around is of course not limited to just websites; using encrypted variables you can get really creative.

The principle of encrypted environment variables works on most CI platforms: Travis-CI, AppVeyor (windows os), Shippable, Wercker and many more.

Demo

This repository and it's github.io page are the demo.

Refer to the content of the master branch to see the configurations used for this specific site. Check the Gruntfile and .travis.yml for the configuration.

View the output in your browser, and check the gh-pages branch to see the output. Have a look at the generated commit messages that link to the diff of the source commits.

This bare-bones demo will render the README.md to html using grunt-markdown. This is a simple example to show the general process, but the flow can be used with any site generator (for example we use it with docpad).

There are many great Grunt plugins, and you can use Grunt to work with pretty much any npm module or shell command.

Is this safe?

It is safe when your build is configured correctly and doesn't print your decrypted secret information to pubic logs on Travis, in the Git commit message or anywhere else.

Having the encrypted values in public repositories is safe because the public/private-key encryption: only in a Travis build of this specific repository will the variables be readable for the running code.

Make sure you read the safety-section further in this guide for the details.

Prerequisites

Intermediate skills

Have some runtimes installed:

Prepare Travis:

$ gem install travis

Guide

Follow these steps to set things up for you project. To get started you can copy the code from this live example.

Create a project that generates a static site

To keep the example simple we use grunt-markdown to convert the README.md to html, wrapped in a simple template.

Create a 'gh-pages' branch on github.com

Configure the 'grunt-gh-pages' plugin

Do a publish test

Activate the Travis webhooks for your project

Configure Grunt to recognise Travis

if ( process.env.TRAVIS === 'true'
        && process.env.TRAVIS_SECURE_ENV_VARS === 'true'
        && process.env.TRAVIS_PULL_REQUEST === 'false'
) {
    grunt.log.writeln('executing deployment');
    grunt.task.run('gh-pages:deploy');
}

Create your '.travis.yml' in the project root

Create an OAuth token for your Github account

Add the token to the secure section in '.travis.yml'

$ travis encrypt GH_TOKEN=your_oath_token --add

Deploy your site

Wrap it up

Online editing

Safety

You should be aware of the main situations that could be bad:

  1. Pushing to the wrong branch or repository (mildly bad)
  2. Leaking your un-encrypted token (really bad)

Always double-check your settings and development logs.

If you leak your token just revoke it quickly and maybe check your Github security activity. Then create a new token, again making sure you limit the scope. A token is harmless after you revoked it.

If you need to print the hidden output of a task that is using your encrypted variables and there really is no other way then you could opt to allow the task to leak it to the logs, as long as you immediately revoke that token. Don't forget this or somebody will pwn your repositories (Murphy's law also works on the internet).

Keep in mind that anyone with commit access to the repository can modify the Grunt configuration to output the decrypted token to the build log. So make sure you trust your collaborators and verify no hostile code lands in your branch (check pull requests etc). NPM operates on trust and reviewed code and is generally safe, but still be smart and don't use flaky plugins. You could opt to lock your dependency semvers or shrink-wrap your build so you can control what dependency version get installed.

If you need this to work in a project with many collaborators and don't want to expose your whole account then you can create a machine user (bot account). Then give the bot commit access to your shared repository and create an OAuth token for it's account. Github allows this, see https://help.github.com/articles/managing-deploy-keys#machine-users.

Travis

Github

Grunt

Local commands

These work for the example Gruntfile from this repository.

Have global grunt command

$ npm install grunt-cli -g

Install dependencies

$ npm install

Rebuild demo page in ./public

$ grunt build

Clean ./public

$ grunt clean

Build & push website using CLI username/password

$ grunt publish

Thanks

Contributing

Contributions are very welcome. Fork the project, make your changes and send a pull request.

Licence

Creative Commons License This work is licensed under a Creative Commons Attribution 4.0 International License.

Generated at 2014-06-08T15:07:02.622Z