Tighten’s Jigsaw, GitHub Pages and GitHub Actions

This blog was previously powered by Tighten’s Jigsaw project. Even though it’s no longer used, if you’re thinking about starting your own blog, I can still highly recommend it.

Since Jigsaw generates a static website, I chose to host it with GitHub Pages as a "user site" as they allow for top-level domains. GitHub Pages only serve static sites, but as Jigsaw is a dynamic system we need to generate the site. I was able to automate this process with GitHub Actions. It took some trial and error (read: a lot of wip commits) but I was finally able to make it work and wanted to share this setup as I think it’s pretty sweet.

I’ll break this down into two sections, the first, using Jigsaw and GitHub Pages and the second, publishing with GitHub Actions.

Jigsaw & GitHub Pages

Jigsaw provides instructions on how to use GitHub Pages, but it’s written for project sites and not user sites. If you’re not sure why this is a problem, it’s because user sites require that the site contents are in the master branch, whereas repository sites default to gh-pages - though that can be changed.

To get this working, I setup Jigsaw under a source branch which contains all of the code, assets and post content. I then push the contents of the build_production directory to the master branch, which GitHub happily serves up for you to read.

It’s a small change, but it may not immediately be obvious, so it’s worth clarifying!

Jigsaw & GitHub Actions

Jigsaw is really, really good but I’m lazy and don’t want to manually be building my website, committing and publishing it after each post.

Admittedly, it took me a lot of time to figure these steps out, but now I’m able to write a new post and have GitHub automatically build and publish it for me!

I created a new workflow under .github/workflows/build-publish.yml with the following:

name: Build & Publish

on:
  push:
    branches:
      - source
  schedule:
    - cron: "0 2 * * 1-5"

jobs:
  build-site:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Install Composer Dependencies
      run: composer install --no-ansi --no-interaction --no-scripts --no-suggest --no-progress --prefer-dist
    - name: Install NPM Dependencies
      run: npm install
    - name: Build Site
      run: npm run production
    - name: Create CNAME File
      run: echo "james.brooks.page" >> build_production/CNAME
    - name: Stage Files
      run: git add -f build_production
    - name: Commit files
      run: |
        git config --local user.email "[email protected]"
        git config --local user.name "GitHub Actions"
        git commit -m "Build for deploy"
    - name: Publish
      run: |
        git subtree split --prefix build_production -b master
        git push -f origin master:master
        git branch -D master

It may look complicated, but we can break it down.

1. We tell GitHub to only run the workflow on pushes to the source branch. I also opted to automatically run the workflow at 2PM Monday - Friday, just in case 🤷🏻‍♂️
2. Next we’re installing the Composer and NPM dependencies.
3. Once the dependencies have been installed, we build the site using the production environment configuration.
4. Optional! I’m using a CNAME on GitHub Pages so that I can use my own domain. I create a new file and fill it with the domain name I want to use.
5. I forcefully stage the build_production directory, this is because Jigsaw defaults to ignoring build_* directories from Git and I don’t want to change this and accidentally publish it into the source branch.
6. Next we configure Git’s email and name, I chose to use GitHub Actions as the author so that I know it’s an automatic commit. We then commit the contents with a pre-defined commit message.
7. Finally, we’re going to publish the site by pushing the changes from within the GitHub Action itself! This is a bit complicated if you’re not confident with Git, but let’s try to keep it simple. We create a subtree of the build_production directory and pushing it into a temporary master branch. Now we can force push the branch to GitHub and clean up by deleting the master branch¹.

And that’s it, I’m now able to write new blog posts without my laptop (using just the GitHub website) and have them immediately published for me.

Let me know @jbrooksuk if you’re using this technique or have any suggestions on how to improve it.

Footnotes

1. Because we’re force-pushing to master from a branch which contains only one commit, all history is lost for the published website. This is a trade-off that I’m happy with because the real history is in the source directory.