Moving away from Travis, configure Circle CI to deploy Github Pages

Why moving away from Travis?

After reading https://news.ycombinator.com/item?id=19218036 and having a friend that just joined Travis, and telling us that the environment there is not anymore the best one, I decided to take action and moving away from it.

A couple of options

Azure pipelines was my first choice but I found it too much complicated and “corporate oriented” for my projects, which are all very small and I don’t need complex pipelines.

I already worked with Circle Ci, also professionally and I actually liked it, so I decided to migrate to that because the configuration is quite simple.

Deploy a simple node frontend to Github pages

The project that we will talk about is my personal website: https://github.com/unsign3d/lucabruzzone.me.

The stack is very simple, markup with PUG and SASS for styiling (probably I will have some node scripts in the future to make the website more “dynamic” in the content).

The configuration

Building it’s pretty easy, I just have a yarn install and a yarn build command based on Parcel JS.
Builds are created at every commit and they output in a dist folder, I’m omitting the code because it’s standard Parcel.

This configuration has a lot on it but it’s pretty simple, we will break down some of the concepts

I have a workflow with 2 steps, one is the build and the other one is the deploy

Building

Building runs the 2 standard npm scripts, install and build, there are some important notes tho.

  • In order to speed up (actually a lot) the build I’m caching 2 folders node_modules, so we won’t download all the packages every time, and .cache, so parcel will already have intermediate steps for the build, and the build of small changes will be super quick (which is mostly my case)
  • In order to be able to deploy, I’m using workspaces, I find that the documentation for that feature is not the best one, so I will do a tl;dr of how I managed to make it work after some googling:
    - Create a working_directory, so that you know where the code is
    - Point the root of the workspace to your ./ (also the working_directory should be fine) and the path should be your artefact folder (in my case dist) with persist_to_workspace

Deploying

First of all you will need to create a new key with read and write access to Github. You can follow the key creation guide here https://circleci.com/docs/2.0/add-ssh-key/ and you will need the public key in Github as a deployment key, you can find here https://developer.github.com/v3/guides/managing-deploy-keys/ some documentation. Remember to give write access to the repo, we will commit and push to that.

Configure your git account, so that you can push, and then a couple of steps will make your life easier

  • Parcel doesn’t create by default the CNAME in the folder, so at every deploy your website will go down if you have a custom domain. You can fix it in 2 ways: you can commit a new file in a separate commit, or add the file before commit, in my case the easiest solution is to create on the fly the file and commit it
  • You don’t want the build to run on the gh-pages branch, it will break because it will not contain the build information (and it doesn’t make sense), so you can ignore the branch from the jobs in the workflow.
    Another similar case it’s that you will want to deploy just the master branch, this is the same case as before but instead of a blacklist approach, you will just whitelist master.
    In case you have a staging gh-pages you can configure a similar job but for the other branch/repo
  • Add your ssh key fingerprint to the deploy step, this will enable you to have access to the repo and the ability to push in that branch

Off topic consideration

If you want to move your website to an S3 + CDN option you will just need to modify slightly the deploy step to have the deploy with the aws cli instead of the gh-pages CLI but the core concept should be mostly the same.