I have an Eleventy site in a Github repo and I want to publish it, what could be more logical or easier than pushing it to Github Pages?

Well, the process was relatively easy but there was still enough gotchas to make it worth recording the lessons learned. First off the Eleventy documentation for Github Pages is not great, I ended up using the Starter Template for Jekyll combined with the Vite documentation but I think a few of my problems came from mashing up my sources.

First things first, you have to manually set your repo’s project Pages setting to Github Actions for anything to happen. I thought the Github Actions could somehow set this up via the configure Pages action but it is a cart before horse situation.

I had quite a few obscure YAML parsing errors and you don’t get any more detail back than “your file is wrong”. I found the action linter invaluable but I also faced a problem that my syntax problem was being reported on the job name but the actual problem was further down from the reported line. Cutting and pasting segments into the linter eventually allowed me to track down the problematic statement and get a parsed file.

Permissions on a job are not additive to the base permissions but override them. I thought I was adding a permission at the job level but I was in fact resetting them.

Having the permissions wrong resulted in an obscure error message Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable which is the authorisation endpoint for an API action. The reason it is unavailable is that the permission isn’t set for the execution context.

Github Pages will publish to <Github username>.github.io/<repo name> which means that by default all the Eleventy generated links will be wrong. You need to use the Base plugin (confusing named to suggest an affinity to the base element) but totally different.

Concurrency was interesting and people seem to do a lot of different things. My conclusion is that the deployment job should only have one instance but shouldn’t be cancelled. If you have a build job that can be split by branch and should be cancelled if a new job is triggered.

Having different concurrency rules seems to be a big reason for splitting up the build and deployment activities, otherwise just having one end to end job seems easier to work with.

I should probably have gone with a starter template (you get offered them when you switch on Github Actions for a repository), unless you’re using a specific tool the static template seems the best. From here you just need to replace the artifact upload action with a build and upload step.