Publishing a static site with Github Pages and Travis CI

Github Pages

When trying to find instructions on how to publish into Github Pages, I found that is was not very clear when trying to publish a static site. 

I thought it would be good to write a guide on publishing a static site into Github Pages and hopefully eliminate any confusion in trying to do so.

Before you start

About this post:

  • 2 – 7 min average reading time
  • Suitable for beginner’s through to advanced

What you will gain reading this post:

  • A guide on how to publish your documentation automatically

What you can do to help support:

  • Like, comment and share this article
  • Follow this blog to receive notifications of new postings

Now, let’s get started.

Steps

  • Check your project into Github > master branch
  • Create a Github Token
    • Click on your profile > Settings > Personal Access Tokens
Github personal access token Diagram
  • Create a .travis.yml file to build your project
  • Log into Travis CI and add the GITHUB_TOKEN environment variable.
    • Select the project repository > More Options > Settings
travis ci environment variables Diagram
  • Ensure your project repository is enabled
travis ci enable repo Diagram
  • Trigger a build if it does not automatically happen when you enable the project repository
    • You will now have a gh-pages branch created and pushed to Github
    • You will now have the static site publish to Github Pages
Github settings github pages Diagram

Let me break it down

In short all the hard work is done in Travis CI, meaning…

language: node_js
install:
- npm install
script:
- npm install codecov -g
- npm run test
- npm run styleguide:build
after_success:
- codecov
deploy:
provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN # Set in travis-ci.org dashboard, marked secure
keep-history: true
local-dir: styleguide

language: Tells Travis CI that the project is a node project and will make available node and npm

install: will run a list of any install commands required before script execution, in our case installing npm dependencies

script: will run a list of commands to build our project, in this particular example I am running npm run styleguide:build which will build a static site.

after_success: will run a list of commands after your build has succeeded

deploy: this step is what actually pushes the static site into Github Pages after every build

  • specifying the provider as pages lets Travis CI know your deploying to Github Pages
  • skip-cleanup will ensure that after building the folder you are trying to deploy, it will not be deleted before it becomes deployed
  • github-token ensure you deployer task as enough privilege to push to Github Pages
  • keep-history will ensure that a force push is not performed
  • local-dir is the directory you are pushing to Github Pages, in our case it is the static site that got created from our script command npm run styleguide:build earlier

Congratulations, on publishing a static site with Github Pages and Travis CI.

Benefits

  • Easy, quick and simple to setup with none to minimal maintenance
  • Code and documentation in one repository
  • Automated deployment of your static site every time you push your code to Github
  • Free hosting of your static site

References

Travis CI to Github Pages deployment documentation
Github Pages documentation

Did this help?

  • Like, comment and share this article
  • Follow this blog to receive notifications of new postings
  • View previous postings

One thought on “Publishing a static site with Github Pages and Travis CI

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.