automated deploy with build-ghpages
Following the advice in Brandon Walsh’s warning, “anything that gets in the middle will keep you from blogging,” I simplified the steps to update and publish my website because the situation was getting a little miserable.
GitHub Pages is a great way to host your static sites free, if you don’t mind keeping your code public. It’s an especially smooth experience if you produce your site with Jekyll because it enjoys built-in support on this hosting platform. In other words, when you upload your Jekyll code to a public GitHub repository and activate GitHub Pages, the site will deploy automatically and become live within seconds (unless something goes wrong).
But I am using 11ty, a JavaScript-based framework, and while it’s common to host other kinds of static websites on GitHub besides Jekyll, it does add some extra steps. I was so close to publishing my website, I really didn’t want to stop for the ideal solution, so I created one main branch for deployment and another deploy one to serve the html files produced after 11ty parsed my root directory. This meant manually copying, pasting, and replacing old html files for newer ones between these 2 branches to keep the site updated. It got old quick. So quick changing this workflow became my top priority issue within the site.
Thankfully, I complained about it to Brandon at the Lab the other week, and he suggested I look for an 11ty version of a “Rakefile,” a document he uses to include custom website build and deployment instructions in his Jekyll website. Some digging pointed out that GitHub Actions might be the easiest way to go.
Using Actions involves changing a setting in your repository, a 1-line edit to your package.json, and a YAML file describing your desired build and deploy workflow for GitHub Pages to host your site. True, I didn’t know what my desired workflow file should look like, but Google turned up a useful Mini-Tutorial in the 11ty documentation that explains the full deploy process and shares a YAML example ready for you to copy and use within your web project.
This worked, but I really didn’t know what was going on in the file at all, so I asked Claude Code 2.1.109 to make me a deploy.yaml file to deploy my 11ty site on GitHub Pages. The file that came out, frankly, works just as fine for my purposes the sample one. One notable difference was the simplicity of Claude’s YAML vs the sample one in the official 11ty documentation, which is thorough and filled with many options to understand.
I stuck to using the sample YAML in 11ty’s docs because it’s safer and adds caching to the deploy workflow, for example.
I kept the simpler Claude Code deploy until I felt that I had a general sense of what was going on in the file. GitHub’s “Workflow Syntax” page was key to understanding what is going on in the file, and what the commands mean. It’s messy, though, and hard to navigate. I skimmed through 75% of it before I found the answer to one of the questions that bothered me the most: “What the heck is that actions/setup-node@v4 doing?” I knew it was setting up Node.js version 4, somehow, but how? Turns out it’s accessing and serving a contained version of Node used by through GitHub Actions to parse and deploy my 11ty site.
name: Deploy
on:
push:
branches: [main]
concurrency:
group: pages
cancel-in-progress: true
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- uses: actions/configure-pages@v5
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./_site
deploy:
needs: build-and-deploy
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: $
steps:
- uses: actions/deploy-pages@v4
id: deploy
Figure 3. Code block with the simpler GitHub Actions workflow generated by Claude Code 2.1.109 to build and deploy my 11ty website. A.k.a. deploy.yaml