What GitHub Actions actually automates for 404cache

An older version of this article described preview environments, automated promotion, backups, newsroom governance, and measured time savings. Those were plausible GitHub Actions patterns, but they were not the 404cache workflow. This Build Note replaces that catalogue with what the public repository can support.

At the time of writing, 404cache has three workflow files in .github/workflows. Each solves a smaller job.

1. CI checks pull requests and main

The ci.yml workflow runs for pull requests and pushes to main. Its checked-in sequence is:

1. check out the repository;
2. select Node.js 20;
3. restore or install node_modules without creating a lockfile;
4. restore the Next.js and Contentlayer caches;
5. run lint;
6. validate content relationships and canonical URL casing;
7. build the exported site.

This is the main safety net. It proves that the code and content compile together; it does not prove that every statement in an article is true or that every interactive path works in a browser.

The two caches have different keys. node_modules follows package.json, while the Contentlayer cache follows the schema and data/**. That division mirrors the expensive work in this repository, though cache effectiveness should be measured from workflow logs before claiming a time saving.

2. The post counter maintains one small statistic

blog-count.yml runs on Monday mornings or by manual dispatch. It counts MDX files under data/blog, writes the result, then force-pushes a dedicated blog-counter branch.

Its write permission is explicit:

permissions:
  contents: write

That permission is justified by the commit step, but the workflow is intentionally isolated from the normal publishing branch. It also counts legacy blog files only, so migrated Guides and Build Notes are not part of that number. That limitation is now documented rather than hidden behind a general “content automation” claim.

3. The development journey generator commits artefacts

devjourney.yml reacts only when its configuration, scripts, or notes change. It sets up Python, runs the generator, and uses a third-party auto-commit action to update the generated journey files.

This is automation with a deliberately narrow trigger. Ordinary editorial changes do not need to regenerate the journey archive.

What remains manual

The repository does not show Actions workflows for social promotion, scheduled article publishing, off-site backups, Search Console submission, or deployment to multiple hosts. It would be misleading to describe those as Adam's experience.

Editorial judgement also remains manual. CI can catch a broken relation or failed build, but it cannot decide whether a first-person claim is evidenced, whether a source is strong enough, or whether two articles should be merged.

Reusable lesson

Start with checks the repository can enforce and keep permissions close to the job. A compact workflow that runs the project's real validation commands is more valuable than copied YAML for systems the project does not use.

For the publishing side of that pipeline, the robots.txt and sitemaps guide explains what 404cache generates and what still needs human review.