Stop Letting Your README Rot: Auto-Sync It on Every Push
Stop Letting Your README Rot: Auto-Sync It on Every Push Every developer has lived this: you clone a repo, follow the README's install instructions, and they don't work. The flags changed. The env vars changed. The quickstart references files that no longer exist. The README is lying to you, and it's nobody's fault — it's just that updating docs is the chore everyone postpones. I got tired of it,…
This article explains how to automatically update a README file on every push to a GitHub repository. Developers often face issues where the README does not reflect the current state of the code, causing confusion for new contributors and users. The solution presented is a GitHub Action called ReadmeForge, which keeps the README file in sync with the codebase.
The process is simple to set up. Developers need to add a workflow file named readme-sync.yml to their repository. This file triggers the action on every push to the main branch. Inside the workflow, there is a job called sync, which prevents the bot from triggering itself and sets the permissions for writing to the repository. The action uses the actions/checkout@v4 and haimhm/readmeforge-action@v1 to compute the differences between the pushed code and the previous commit, and then sends this diff along with the current README to the ReadmeForge API.
The ReadmeForge API then generates an updated README file based on the differences and creates a pull request for review. The default mode is to open a review PR, ensuring that any changes are reviewed by a human before being merged. If the changes are not relevant to the documentation, the action exits quietly without making any changes to the README.
Two configuration options are available: mode: pr, which is the default and opens a review PR, and mode: commit, which pushes the updated README directly to the branch (available on the Pro tier).
The free tier of ReadmeForge offers 20 syncs a month on public repositories, which is usually sufficient for most side projects. For private repositories, more volume (1,000 syncs/month) or direct-commit mode, the Pro tier is available at $9/month via Gumroad. To enable the Pro tier, developers need to add a license key as a repository secret and pass it to the action using the SECRET READMEFORGE_LICENSE_KEY.
By automating the process of keeping the README in sync with the codebase, developers can save time, reduce the chance of stale documentation, and improve the overall experience for new contributors and users. The entire setup can be done in just two minutes, making it an efficient solution to a common problem in software development.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
