GitHub Actions on Not That Kind of Agent

Hardening GitHub Actions workflows against supply chain attacks

Wed, 13 May 2026 00:00:00 -0700

I asked Claude Code to review the GitHub Actions workflows in this repo for supply chain attack risk. This post covers what it found, what we changed, and a prompt you can reuse on your own workflows.

The threat model

A supply chain attack via GitHub Actions works like this: a third-party action you depend on (say, some-org/some-action@v2) gets its tag force-pushed with malicious code. On your next workflow run, that code executes in your CI environment. It has access to your secrets and token permissions.

The same risk applies to npm. If a package in your node_modules tree is compromised, its postinstall script runs during npm ci. It can read any credentials in the job environment.

Neither is theoretical. Both attack types have hit real CI pipelines.

What I changed

1. Pin third-party actions to commit SHAs

GitHub’s version tags (e.g., @v2, @v8) are mutable. A tag can be moved to point to a different commit without notice. Pinning to a commit SHA means the code you reviewed is the code that runs, forever.

Immutable vs mutable

Git tags are just labels. The v8 tag is a pointer, and whoever controls the repo can move it to a different commit. Same name, different code. That’s what mutable means here.

A commit SHA is different. Git derives it from the content of the commit, so it can only refer to that one thing. You can’t redirect it.

That’s what makes SHA pinning an actual security control. Once you’ve reviewed what’s at a given SHA, nobody can swap something else in without you noticing.

I was using two third-party actions:

1
2
3
4
5
6
7


# Before
uses: peter-evans/create-pull-request@v8
uses: errata-ai/vale-action@v2

# After
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2

The # v8 comment keeps it human-readable. To get the SHA for a tag:

1

gh api repos/peter-evans/create-pull-request/git/ref/tags/v8 --jq '.object.sha'

GitHub’s own first-party actions/* are lower risk, but if your threat model requires it, the same pinning applies.

2. Add explicit `permissions` blocks

Without an explicit permissions block, a workflow job inherits the repository’s default token permissions, which can be read/write depending on repo settings. Declaring minimum permissions limits what an attacker can do with a compromised token. This is the security principle of “least privilege.”

Three of my workflow files had no permissions block at all:

1
2
3


# Added to lint.yml, security.yml, vale.yml
permissions:
 contents: read

The deploy.yml and update-theme.yml workflows were already scoped correctly. deploy.yml needs pages: write and id-token: write for GitHub Pages deployment. update-theme.yml needs contents: write and pull-requests: write to create automated PRs.

3. Set `persist-credentials: false` on checkouts that don’t need to push

By default, actions/checkout writes the GITHUB_TOKEN into .git/config where it stays accessible to every subsequent step in the job. That includes npm ci, which runs third-party postinstall scripts.

For jobs that check out code but never push (linting, security scanning, prose review), there’s no reason for the credential to persist:

1
2
3


- uses: actions/checkout@v6
 with:
 persist-credentials: false

I applied this to lint.yml, security.yml, and vale.yml. The deploy.yml and update-theme.yml workflows keep the default because they run git operations that need authentication.

4. Add `timeout-minutes` to every job

Jobs without a timeout run for up to 6 hours by default. That’s a long window of live token exposure if something goes wrong. Tight timeouts also limit the damage from a hung or hijacked job.

1
2
3
4


jobs:
 lint:
 runs-on: ubuntu-latest
 timeout-minutes: 5

Each of these jobs completes in seconds, with the build and deploy pipeline taking under two minutes. I set all jobs to 5 minutes. That’s a reasonable buffer given actual run times, and a lot better than leaving the 6-hour default in place.

The prompt

Here’s the prompt I used. It works well with Claude Code in a repo with workflow files present:

Review the GitHub Actions workflows in .github/workflows/ for supply chain attack risk. For each workflow file, check:

Action pinning — Are any third-party actions (non-actions/*) pinned to a mutable version tag instead of a commit SHA? If so, fetch the current SHA for each tag using gh api repos/<owner>/<repo>/git/ref/tags/<tag> and pin them. Add the version tag as a comment for readability.

Permissions — Does every job have an explicit permissions block declaring the minimum required scopes? If not, add one. Jobs that only read code should use permissions: contents: read. Note which jobs legitimately need write scopes and why.

persist-credentials — Does actions/checkout default to persisting the GITHUB_TOKEN into .git/config? For any job that does not need to git push, add persist-credentials: false to the checkout step. This prevents the token from being readable by npm postinstall scripts or other downstream steps.

Timeouts — Does every job have a timeout-minutes value set? If not, add one. Base the value on a realistic upper bound for that job’s expected runtime.

For each finding, explain the risk and make the change. Do not pin GitHub’s own first-party actions/* actions unless I ask — focus on third-party dependencies.

Run this against a repo with a clean working tree. The diff lands in one place, which makes it easier to spot anything unexpected before you commit.

What this doesn’t cover

This review focuses on the workflow files themselves. It doesn’t cover:

Repository secrets — if you have a personal access token (PAT) with broad org-wide scope stored as a repo secret, that’s a higher-impact risk than anything in the workflow YAML. Audit your repo and org secrets separately.
pull_request_target — workflows using this trigger run with write permissions even for PRs from forks, which can give fork contributors unintended write access to your repo. None of my workflows use it, but it’s worth checking yours.
Dependabot for Actions — automatically opens PRs to bump action versions. Pairing it with SHA pinning requires extra config but keeps pinned SHAs from going stale.

Fixing error: GitHub Actions isn't allowed to open pull requests

Wed, 06 May 2026 00:00:00 -0700

In my last post, I updated the update-theme workflow to open a pull request instead of committing theme updates directly to main. Smart in theory. In practice, when the workflow needed to open a pull request to bump the hugo version, it failed. The workflow run also warned me about Node 20 actions being deprecated.

I used Claude Code to help diagnose and work through both issues. This post is my note-to-future-self on what needed to change and where.

Problem 1: GitHub Actions isn’t allowed to open pull requests

The workflow failed with this error from the GitHub REST API:

GitHub Actions is not permitted to create or approve pull requests.

The peter-evans/create-pull-request action uses the built-in GITHUB_TOKEN to open PRs. The workflow already had the right permissions declared:

1
2
3


permissions:
 contents: write
 pull-requests: write

But there are two separate settings in the repository that also need to be enabled, and both were off by default.

Setting 1: Actions allowlist

Go to Settings → Actions → General and look at the “Actions permissions” section. If you’re using the “Allow [org], and select non-[org], actions and reusable workflows” option, you need to explicitly list the third-party actions your workflows use in the allowlist field.

Here’s what I added:

1
2
3


peaceiris/actions-hugo@*,
peter-evans/create-pull-request@*,
errata-ai/vale-action@*

The @* wildcard covers any version tag, so this doesn’t need updating when action versions get bumped. GitHub’s own actions (actions/checkout, actions/setup-node, etc.) are covered separately by checking “Allow actions created by GitHub”.

Setting 2: Workflow permissions

Further down on the same Settings → Actions → General page is the “Workflow permissions” section. There’s a checkbox labeled “Allow GitHub Actions to create and approve pull requests” that is unchecked by default. Check it.

This is a separate gate from the permissions: block in the workflow YAML. Even with pull-requests: write in the workflow, the GITHUB_TOKEN cannot open PRs unless this repo-level setting is also enabled.

After enabling both, the workflow ran successfully and opened its first PR.

Problem 2: Node.js 20 deprecation warnings

With the workflow actually running, a new batch of warnings appeared:

Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4, peaceiris/actions-hugo@v3, peter-evans/create-pull-request@v7. Actions will be forced to run with Node.js 24 by default starting June 2nd, 2026.

Node.js 20 reached end-of-life in April 2026. GitHub Actions is forcing a cutover to Node.js 24 on June 2nd, and removing Node.js 20 from runners entirely on September 16th.

This affected every workflow in the repo, not just update-theme. Claude Code helped me audit all five workflows and figure out what could be upgraded versus what needed a workaround.

Action version bumps

Several actions had new major versions available with Node.js 24 support.

Cross-workflow updates (applied to all five workflow files where used):

Action	Before	After
`actions/checkout`	v4 / v5	v6
`actions/setup-node`	v4	v6
`peter-evans/create-pull-request`	v7	v8

deploy.yml-specific updates:

Action	Before	After
`actions/setup-go`	v5	v6
`actions/configure-pages`	v5	v6
`actions/cache`	v4	v5
`actions/upload-pages-artifact`	v3	v5
`actions/deploy-pages`	v4	v5

Actions that don’t have a Node.js 24 release yet

One action was already at its latest major version with no Node.js 24-compatible release available:

errata-ai/vale-action@v2 (used in vale.yml)

For it, I added the opt-in environment variable to the affected job:

1
2


env:
 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

This tells the runner to use Node.js 24 for that action now, before GitHub forces it on June 2nd. If it breaks, that’s a signal to find an alternative or wait for an upstream update.

peaceiris/actions-hugo@v3 was in the same situation — no Node.js 24 release, same warning — but I replaced it entirely rather than applying the workaround. See below.

Replacing peaceiris/actions-hugo

peaceiris/actions-hugo@v3 is an unmaintained community wrapper that downloads Hugo from GitHub releases and puts it on PATH. Since it has no Node.js 24-native release and is just a thin wrapper around a direct download, the right move was to remove the dependency and do the download directly — the same pattern already used for Dart Sass in deploy.yml.

In deploy.yml, where the Hugo version is pinned in an environment variable:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


- name: Setup Hugo
 run: |
 mkdir -p "${HOME}/.local/bin"
 curl -sLo "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \
 "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
 curl -sLo "hugo_checksums.txt" \
 "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_checksums.txt"
 sha256sum --check --ignore-missing "hugo_checksums.txt"
 tar -C "${HOME}/.local/bin" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" hugo
 rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" "hugo_checksums.txt"
 echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

In update-theme.yml, where the workflow always wants the latest Hugo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


- name: Setup Hugo
 env:
 GH_TOKEN: ${{ github.token }}
 run: |
 HUGO_VERSION=$(gh release view --repo gohugoio/hugo --json tagName --jq '.tagName | ltrimstr("v")')
 mkdir -p "${HOME}/.local/bin"
 curl -sLo "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \
 "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
 curl -sLo "hugo_checksums.txt" \
 "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_checksums.txt"
 sha256sum --check --ignore-missing "hugo_checksums.txt"
 tar -C "${HOME}/.local/bin" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" hugo
 rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" "hugo_checksums.txt"
 echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

The sha256sum --check --ignore-missing step verifies the tarball against Hugo’s published checksums file before extracting. --ignore-missing is needed because the checksums file covers all platforms and editions; we only downloaded one of them. This is something peaceiris/actions-hugo never did, so the replacement is actually a supply chain improvement over what it replaced.

Aligning the pinned Node.js version

While auditing the workflows, I noticed the pinned node-version values were inconsistent:

Workflow	Node version (before)
`deploy.yml`	`24.12.0`
`lint.yml`	`22`
`security.yml`	`20`

Node.js 22 is now in Maintenance LTS (its Active LTS phase ended October 2025). Node.js 24 is the current Active LTS and what deploy.yml was already using. I updated lint.yml and security.yml to '24' so all workflows are consistent.

The two things to remember

If you set up a GitHub Actions workflow that opens PRs and it fails with a permissions error, check both places:

Settings → Actions → General → Actions permissions — add third-party actions to the allowlist
Settings → Actions → General → Workflow permissions — enable “Allow GitHub Actions to create and approve pull requests”

The permissions: block in the workflow YAML is necessary but not sufficient on its own. You need the repo-level checkbox too. Future me: check there first.

When Your Theme Auto-Updates But Your Build Environment Doesn't

Wed, 29 Apr 2026 00:00:00 -0700

While poking around my Tugboat Dashboard, I noticed the base preview for the main branch in this repo had failed. The site was still working, and it wasn’t until today that I needed to get pull request previews up and running again for this repo. The error was a bit cryptic at first glance, but it turned out to be a straightforward version mismatch with a less-than-straightforward paper trail.

I used Claude Code in VS Code to help me diagnose and fix the error, and we worked together to devise a plan to update the update-theme workflow and Tugboat to be more resilient to automatic changes and to put me—the human—in the loop when needed. Claude Code helped me write a detailed PR description and turn this incident into a blog post, which I edited and added to. Robot teamwork!

The error

1
2
3
4


WARN Module "github.com/CaiJimmy/hugo-theme-stack/v4" is not compatible
 with this Hugo version: Min 0.157.0 extended
ERROR error building site: ... at <reflect>: can't evaluate field
 IsImageResourceWithMeta in type interface {}

Two errors, one cause. The theme (hugo-theme-stack) had been auto-updated to a version that requires Hugo 0.157.0 extended as a minimum. My Tugboat config was pinned to Hugo 0.155.3. The IsImageResourceWithMeta template error isn’t a separate bug—it’s what happens when the theme tries to use a field that doesn’t exist in the older Hugo version.

How did this happen?

This site’s repo includes a GitHub Actions workflow, .github/workflows/update-theme.yml, that runs on a daily cron schedule:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


- name: Update theme
 run: hugo mod get -u

- name: Tidy go.mod, go.sum
 run: hugo mod tidy

- name: Commit changes
 uses: stefanzweifel/git-auto-commit-action@v5
 with:
 commit_message: 'CI: Update theme'

That workflow installs hugo-version: 'latest' and then runs hugo mod get -u, which pulls the latest version of the theme and commits the result directly to main. No build validation, no review step. When the theme bumped its minimum Hugo requirement, the workflow committed the update anyway, the main branch now had an incompatible theme version, and Tugboat’s next preview build failed.

The version mismatch lived in two different config files that had no awareness of each other:

File	Hugo version
`.github/workflows/update-theme.yml`	`latest` (always current)
`.tugboat/config.yml`	`0.155.3` (manually pinned, stale)

The immediate fix

The quickest fix was updating .tugboat/config.yml to install a Hugo version that satisfies the theme’s requirements. Hugo 0.161.1 is the current latest release, so I bumped the download URL there:

1
2
3
4
5


# Before
- curl -Ls https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_extended_0.155.3_Linux-64bit.tar.gz | tar -C /usr/local/bin -zxf - hugo

# After
- curl -Ls https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_extended_0.161.1_Linux-64bit.tar.gz | tar -C /usr/local/bin -zxf - hugo

That unblocks Tugboat, but it doesn’t prevent the same thing from happening the next time the theme bumps its minimum Hugo requirement. I needed to rethink the workflow.

Making it future-proof

The core problem is that the workflow had no feedback loop: it updated the theme, assumed everything was fine, and committed. I made three changes to address that.

1. Auto-sync the Tugboat Hugo version (automated)

The workflow already installs the latest Hugo to run hugo mod get -u. After updating the theme, I extract that version number and rewrite the download URL in .tugboat/config.yml to match:

1
2
3
4


- name: Sync Hugo version in Tugboat config
 run: |
 HUGO_VERSION=$(hugo version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
 sed -i -E "s|/download/v[0-9.]+/hugo_extended_[0-9.]+_Linux-64bit|/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit|g" .tugboat/config.yml

What does that command do?

The two lines work together to extract the installed Hugo version and rewrite the download URL in .tugboat/config.yml.

Line 1 — extract the version number

hugo version outputs something like hugo v0.161.1+extended linux/amd64 .... The pipeline extracts just 0.161.1:

grep -oE '[0-9]+\.[0-9]+\.[0-9]+' — -o prints only the matching text (not the whole line); -E enables extended regex; the pattern matches any digits.digits.digits sequence
| head -1 — takes the first match, in case the output ever contains more than one version-like string

The result is stored in HUGO_VERSION.

Line 2 — rewrite the URL in `.tugboat/config.yml`

sed -i -E "s|old|new|g" is a find-and-replace on the file:

-i — edit in place (modifies the file directly, no output)
-E — enables extended regex, needed for + to mean “one or more”
s|...|...|g — the substitute command, using | as the delimiter instead of the usual / because the pattern itself contains forward slashes, which would otherwise need escaping

The pattern matches the version-specific portion of the Hugo download URL—[0-9.]+ matches any version number like 0.155.3 or 0.161.1. The replacement plugs $HUGO_VERSION into both spots where the version number appears. The g flag replaces all occurrences, though there’s only one matching line in the file.

Now the workflow keeps both environments in lock-step automatically. Whatever Hugo version the workflow installs and validates against is the same version Tugboat gets in the same commit.

2. Build validation (automated)

After updating the theme and syncing the Tugboat config, the workflow now tries to actually build the site:

1
2


- name: Build site
 run: hugo --gc --minify

If the build fails—bad template, incompatible theme change, anything—the workflow stops here. Nothing gets committed. This is the automated gate: it catches functional breakage before it touches the repo.

3. Open a PR instead of pushing directly to `main` (human in the loop)

Even if the build succeeds, hugo mod get -u is pulling in external code and committing it automatically. A theme update that builds cleanly could still introduce changes worth reviewing—a new JavaScript dependency, a layout change, a modified partial. The original workflow gave no opportunity to see any of that.

I replaced the auto-commit action with peter-evans/create-pull-request, which opens a PR on a branch (automated/update-theme) instead of pushing to main:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


- name: Create Pull Request
 uses: peter-evans/create-pull-request@v7
 with:
 commit-message: 'CI: Update theme'
 title: 'CI: Update theme'
 body: |
 Automated theme update via `hugo mod get -u`. Please review changes before merging.
 branch: automated/update-theme
 delete-branch: true
 add-paths: |
 go.mod
 go.sum
 .tugboat/config.yml

A few details worth calling out:

add-paths scopes the PR to only the three files that should change. The build step generates output in public/, which we don’t want to commit.
delete-branch: true cleans up the branch after the PR merges.
If the theme is already up to date, there are no changes to the specified paths and no PR is opened. No noise on quiet days.
pull-requests: write was added to the job permissions to allow the action to open PRs.

The updated workflow

Here’s the full workflow after these changes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


name: Update theme

on:
 schedule:
 - cron: '0 0 * * *'
 workflow_dispatch:

jobs:
 update-theme:
 runs-on: ubuntu-latest

 permissions:
 contents: write
 pull-requests: write

 steps:
 - uses: actions/checkout@v4

 - name: Setup Hugo
 uses: peaceiris/actions-hugo@v3
 with:
 hugo-version: 'latest'
 extended: true

 - name: Update theme
 run: hugo mod get -u

 - name: Tidy go.mod, go.sum
 run: hugo mod tidy

 - name: Sync Hugo version in Tugboat config
 run: |
 HUGO_VERSION=$(hugo version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
 sed -i -E "s|/download/v[0-9.]+/hugo_extended_[0-9.]+_Linux-64bit|/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit|g" .tugboat/config.yml

 - name: Build site
 run: hugo --gc --minify

 - name: Create Pull Request
 uses: peter-evans/create-pull-request@v7
 with:
 commit-message: 'CI: Update theme'
 title: 'CI: Update theme'
 body: |
 Automated theme update via `hugo mod get -u`. Please review changes before merging.
 branch: automated/update-theme
 delete-branch: true
 add-paths: |
 go.mod
 go.sum
 .tugboat/config.yml

Takeaways

Automation that commits directly to your main branch with no validation is convenient right up until it isn’t. The combination that works better here is:

Automated gates to catch objective failures (the build doesn’t compile, the version numbers are out of sync)
Human review for everything that passes the automated gate but still involves external code landing in your repo

Neither one alone is enough. The build gate would have caught the broken template error in this case—but a future theme update that builds cleanly and introduces something undesirable would still slip through without the PR step. And the PR step alone, without the build gate, would still surface broken builds in review instead of catching them before the PR is even opened.

Layers are good.

New Site, Who Dis

Mon, 09 Feb 2026 15:18:13 -0800

Used Claude.ai to help me choose a template for my Hugo site. Hugo is a static site generator. My prompt:

Help me pick a theme for my personal site running Hugo.

Actively maintained

Accommodates blog posts that can have text, images, YouTube videos embedded.

Responsive layout and typography Nice to have: a gallery layout. Bonus points if it can integrate with Flickr.

Claude recommended Stack, which I agreed with, based on some extensive theme evaluation I had done the previous week.

Hugo Stack—This is my top pick for you. It’s actively maintained (last updated January 2026), has 6,200+ GitHub stars, and includes PhotoSwipe integration for galleries with lightbox functionality. The card-style layout works beautifully for blog posts with mixed media, supports lazy-loading images, has dark mode, and handles YouTube embeds well. The responsive typography is clean and modern.

The Stack theme, self-described as “Card-style Hugo theme designed for bloggers,” doesn’t use the typical Hugo quickstart process for adding a theme to an existing repo using git submodule add.... Since this site is brand new, I was okay with starting from scratch.

The Stack theme repo lives at GitHub: CaiJimmy/hugo-theme-stack. The Quickstart process, using the template at CaiJimmy/hugo-theme-stack-starter, assumes you are starting a brand new site.

It uses Hugo modules feature to load the theme. This means that the theme is downloaded to Hugo’s cache directory and isn’t visible in your repo. Contrast that with the git submodule approach for adding a theme which adds theme code to the themes directory and is managed with git submodule commands. (This was a new concept for me.) Hugo modules are managed with hugo mod commands, which requires Go.
It comes with a basic theme structure and configuration.
A GitHub action (.github/workflows/deploy.yml) has been set up to deploy the theme to a public GitHub page automatically.
Also, there’s a cron job to update the theme automatically everyday.

Goal

Create new Hugo site based on CaiJimmy/hugo-theme-stack-starter template and deploy with GitHub Pages.

Notes

The default branch on CaiJimmy/hugo-theme-stack-starter is master and I want to change that to main. That will mean a few extra steps.

Local development vs. cloud editing

I watched the video tutorial at CaiJimmy/hugo-theme-stack-starter. This demonstrates using GitHub’s Codespaces cloud editor. I decided to use a local development workflow since I am comfortable with that. Going the local development route means I’ll need the following dependencies installed on my Mac:

Git (I’ve already installed this with Command Line Tools, and set up my public key with GitHub.)
Hugo (I already installed this with brew install hugo)
Go (Required by this project, I installed it globally with brew install go)

Steps

If you want to use GitHub Codespaces, follow the steps at CaiJimmy/hugo-theme-stack-starter.

To set up the site for local development, I did the following steps:

On GitHub

On CaiJimmy/hugo-theme-stack-starter, in the upper right corner, click Use this template > Create new repository.
Name the repo <username>.github.io and click Create this repository (or whatever the submit button is called)

To make deployment to GitHub Pages a snap, I named my repo, agentolivia.github.io, where agentolivia is my GitHub username. If you use a different repo name, the site will be deployed to sub-directory of <username>.github.io. Fun facts.

On my Mac, in a Terminal window

cd ~/Sites
git clone git@github.com:<username>/<username>.github.io.git
cd <username>.github.io
git submodule update --init --recursive

Change the `master` branch to `main`

git branch -m master main
git push -u origin main

Back on GitHub

On the repo page, click Settings
Under Settings: Default branch > Switch (arrows icon) > main

Back on Mac, in Terminal window

git push origin --delete master

What we have right now is a broken build which will be fixed by updating .github/workflows/deploy.yml.

Edit deploy.yml

In code editor of choice, open for editing .github/workflows/deploy.yml

Side quest: Install GitHub Actions plugin on VS Code, which popped up when I opened the file in VS Code.

Update the list of branches to match the new default branch, main.

1
2
3
4
5
6


name: Build and deploy
on:
push:
 branches:
 - main
...

Update environment constants to match local.

I noticed that when I checked out the versions I had locally installed, they were a bit different than what was listed in deploy.yml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# hugo
hugo version
hugo v0.155.3+extended+withdeploy darwin/arm64 BuildDate=2026-02-08T16:40:42Z VendorInfo=Homebrew

# go
go version
go version go1.25.7 darwin/arm64

# node
node --version
v24.12.0

Under jobs.build.env, update the version to match the output.

1
2
3
4
5
6
7
8
9


jobs:
build:
 runs-on: ubuntu-latest
 env:
 DART_SASS_VERSION: 1.97.1
 GO_VERSION: 1.25.7
 HUGO_VERSION: 0.155.3
 NODE_VERSION: 24.12.0
 TZ: America/Los_Angeles

Save file and git add .github/workflows/deploy.yml
Commit: `git commit -m “Update deploy.yml”
Push to repo to see deployment in action: git push

Switch to GitHub to see deployment in action

Click on the yellow dot next to the latest commit message, then Details to watch the build!

View live site

Visit GitHub pages site. For me this is at https://agentolivia.github.io.
It should be live with the starter template’s demo content.

I’m now ready to customize the site, unpublish the default content, and add some new posts. (Hey, this is one of them, so I succeeded!)