Using Circle CI with Github Pages for Continuous Delivery

Setting up a Github Pages Project Page with Circle CI

Greetings! This will guide you through a basic setup of a Github pages project with Circle CI. All examples here are meant to be as clear as possible - there may be different and quicker ways to do some of these things, but this tutorial is biased on the side of clarity rather than brevity.

Setting up Github Pages with a project

You need a Github repo with an index.html file in it (for an example, check out My personal website. This tutorial assumes you have merge permissions with the repo.

Now, check out this repository to your workstation and create a new gh-pages branch.

  $ git checkout -b gh-pages

Push this new gh-pages branch to your repo on github

  $ git push origin gh-pages

Now check out http://your-github-name.github.io/your-project-name (i.e. http://nellshamrell.github.io/nell-shamrell-website-version-3/) and you should see your index.html rendered!

Now switch back to your master branch.

  $ git checkout master

And make a minor change to index.html

Now add this change:

  $ git add index.html

And commit it:

  $ git commit -m 'experimental change'

And push it to your master branch

  $ git push origin master

Now, head back to your project's page in your browser at http://your-github-name.github.io/your-project-name

And...you shouldn't see your change. This is because we have only committed the change to the master branch, now we need to merge that change into our gh-pages branch.

Checkout your gh-pages branch.

  $ git checkout gh-pages

And merge master into it:

  $ git merge master

Then push this up to your gh-pages branch on your origin.

  $ git push origin gh-pages

Now take a look at http://your-github-name.github.io/your-project-name. You should see your change!

Setting up Circle CI

(Instructions based on https://github.com/Villanuevand/deployment-circleci-gh-pages)

Now we are going to use Circle CI to automate this merge/deploy process. Whenever we merge something to master, it will automatically merge into the gh-pages branch.

Create Circle CI account

If you do not already have a Circle CI account, head here and create one.

Add your project to your Circle CI account. Check out these instructions for more info.

Create Environmental variables

Now, let's create two environmental variables in Circle CI that we will use to deploy your changes.

Select your project in Circle CI.

Click on the Project Settings link (it's a little picture of a gear wheel).

Click on the Environmental Variables link underneath the "Build Settings" heading in the left hand menu.

Click on the "Add Variable" button.

For the Name, type in "GH_NAME." For the Value, type in your github username (mine would be "nellshamrell"), then submit the form.

After that, click on the "Add Variable" variable again. This time - for the Name type in "GH_EMAIL" and for the value type in your email address associated with your github account.

Create a deploy script

Now, we're going to create a deploy script. We're going to copy the one here.

First, switch back to the master branch.

  $ git checkout master

Then create a directory in your repo called scripts

  $ mkdir scripts

Create a file called deploy-ghpages.sh (here I am using vim, use whatever text editor you prefer)

  $ vim scripts/deploy-ghpages.sh

Then paste this content into the file:

#!/bin/sh
# ideas used from https://gist.github.com/motemen/8595451

# Based on https://github.com/eldarlabs/ghpages-deploy-script/blob/master/scripts/deploy-ghpages.sh
# Used with their MIT license https://github.com/eldarlabs/ghpages-deploy-script/blob/master/LICENSE

# abort the script if there is a non-zero error
set -e

# show where we are on the machine
pwd
remote=$(git config remote.origin.url)

# make a directory to put the gp-pages branch
mkdir gh-pages-branch
cd gh-pages-branch
# now lets setup a new repo so we can update the gh-pages branch
git config --global user.email "$GH_EMAIL" > /dev/null 2>&1
git config --global user.name "$GH_NAME" > /dev/null 2>&1
git init
git remote add --fetch origin "$remote"


# switch into the the gh-pages branch
if git rev-parse --verify origin/gh-pages > /dev/null 2>&1
then
    git checkout gh-pages
    # delete any old site as we are going to replace it
    # Note: this explodes if there aren't any, so moving it here for now
    git rm -rf .
else
    git checkout --orphan gh-pages
fi

# copy over or recompile the new site
#cp -a "../${siteSource}/." .

# stage any changes and new files
git add -A
# now commit, ignoring branch gh-pages doesn't seem to work, so trying skip
git commit --allow-empty -m "Deploy to GitHub pages [ci skip]"
# and push, but send any output to /dev/null to hide anything sensitive
git push --force --quiet origin gh-pages
# go back to where we started and remove the gh-pages git repo we made and used
# for deployment
cd ..
rm -rf gh-pages-branch

echo "Finished Deployment!"

Then go ahead and save and close the file.

Now, we need to make this script executable (otherwise circle ci will return a build error).

Run this command:

  $ chmod+x scripts/deploy-ghpages.sh

Create circle.yml

Now, back at your terminal in your repo, create a file called circle.yml (here I use vim, but use whatever text editor you prefer). You should still be on your master branch.

  $ vim circle.yml

Then paste in this content (from https://github.com/eldarlabs/ghpages-deploy-script/blob/master/circle.yml)

deployment:
  production:
    branch: master
    commands:
    - ./scripts/deploy-ghpages.sh build

Then save and close the file.

Now, add all of this:

  $ git add .

And then commit it:

  $ git commit -m 'Adds in circle ci configs'

Then push it to your master branch.

  $ git push origin master

Creating a machine user

Next, you will need to create a special Github user solely for use by Circle CI. This is because although Circle CI automatically sets up a deploy key that allows them to read from the repo, that key does not have access to write to the repo. For more details on this, see this Circle CI documentation

In order to merge the master branch into the gh-pages branch, then push it to Github, Circle CI needs a key with write access to the repository. While yes, you could give Circle CI your person Github key, I do not recommend that for security reasons. Then Circle CI would have access to push to all repositories that you can push to. Let's create a Github user who will only have access to push this particular repo.

I recommend opening up another browser so you can stay logged into your main Github account in one browser, then create another Github account in the second browser.

In the second browser, create a new Github account. You will need to use a different email address than the one for your main github account (if you use gmail (and some other email providers) you can use an email alias. I like to use something similar to my-repo-machine (i.e. nell-shamrell-website-machine), but you can use whatever name you wish.

Now, head back to first browser (the one with your main Github account). Head to your github repository you are deploying with Circle Ci and add your new machine user as a collaborator on the repo (they need to have push access to the repo).

Head back to the second browser and head to github on your machine account. You should now see an invite to collaborate on the github repo you are deploying with circle ci. Make sure to accept this invite.

Still in your second browser, head to Circle CI and click "Log In", then click on "Log in with Github" - make sure you login with your machine user account!

Click on "Add Projects"

Click on your regular github username (not the machine name) in the "Choose organization" menu.

From the right hand menu, select "Follow project" next to your repo name

Once followed, go to the Project Settings, then "Checkout SSH keys", and then click on the Authorize w/GitHub button.

This will bring you to Github (check that you are signed into Github as the machine user). Click "Authorize Application"

Enter your machine user password at the confirmation screen

You will be brought back to Circle CI.

Finally, click the Create and add machine user github name key button on the same page.

Creating something to deploy

Now, still on your master branch, make a small change to your index.html (small, but noticeable), then add, commit, and push it.

Now head back to your circle ci project page and you should see a new build running. Wait for that build to complete.

Then you should see it deployed automatically to http://your-github-name.github.io/your-project-name!