Tutorial 2: Deploying to GitHub Pages using Circle

In this tutorial, we'll deploy our website that we started in Tutorial 1 to GitHub Pages using CircleCI. By the end of this tutorial, you'll have:

Configuring GitHub

In your GitHub repository's settings page (Settings -> Options -> GitHub Pages), set the "Source" branch to master for GitHub Pages. This tells GitHub that we'll want to deploy whatever is in master as a static website to http://myusername.github.io/my-website.

GitHub Settings: Set pages source to master branch

GitHub Settings: Set pages source to master branch

Now that we're using the master branch for our generated files, we need to move our code into a different branch (e.g. source):

git checkout -b source
git push origin

Our build and deploy scripts will automatically generate commits to master, so you should no longer use that. You'll want to set source as the default branch in the GitHub repository settings (Settings -> Branches -> Default branch).

GitHub Settings: Set base branch to source

GitHub Settings: Set base branch to source

Makefile

Let's generate a Makefile using the script provided by Pencil:

bash <(curl -fsSL https://raw.githubusercontent.com/elben/pencil/master/bin/gen-stack-makefile)

Check out the generated Makefile to make sure that your GitHub username, repo, and project name looks correct.

With this Makefile, you can now just type make to build all your dependencies and generate your website. We'll also use this in the CircleCI build.

CircleCI Configuration

We'll also setup a CircleCI to automatically build and deploy our website whenever we push our source.

In your project's directory, generate the required CircleCI configuration files using this script:

bash <(curl -fsSL https://raw.githubusercontent.com/elben/pencil/master/bin/gen-stack-circle-config)

The CircleCI build plan generated in .circleci/config.yml folder will:

You can read more about the CircleCI configuration here.

Putting it all together

With that, lets commit and push the files to the remote source branch:

git add .circleci Makefile
git commit -m "Add Makefile and .circleci files"
git push

Now we need to set up our project in CircleCI:

  1. Go to the CircleCI dashboard.
  2. Click on "Add Projects".
  3. Add your website repo by clicking "Set Up Project".
  4. In the project setup page, just click on "Start building", since we've already created our .circleci/config.yml file.

At this point, Circle should start building your website. Wait for the build to finish, and Circle should automatically push your generated website to the master branch.

If CircleCI fails to push to GitHub, you may need to set up your SSH keys to have write access to the GitHub repo. Follow the instructions in your project's "Checkout SSH keys" settings page to set up either a user key or a deploy key with write access (circleci.com/gh/your-username/your-project/edit#checkout).

Once the build is done (it may take a while at first as it's downloading and caching all the Haskell dependencies), GitHub will deploy your website to GitHub will then deploy your website to myusername.github.io/my-website

And that's it! You've successfully set up continuous integration. Any new pushes to source will now kick-off a build and deploy.