Repository navigation
Add support for generating READMEs too #282
Description
The existing automatic wiki generation feature is great, but having an option to generate READMEs for released modules will be a great addition. This is handy for situations where you may want to maintain READMEs separately or keep wikis disabled (such as for private repos under the free plan).
Activity
virgofx commentedon Oct 2, 2025
Thanks for the feature request! This would be a valuable addition, especially for users with private repos on free plans or those who prefer to keep wikis disabled.
I want to make sure I understand what you're looking for, especially since this is related to #275 (CHANGELOG.md generation).
Key question: How should the README.md be delivered?
I see a few possible approaches:
Auto-commit to module directories after PR merge (e.g.,
aws/vpc/README.md)Provide as action output
changed-modules-mapoutput)Commit during the PR (before merge)
Also curious about:
The same delivery mechanism questions apply to #275 as well, so understanding your preferred approach here would help guide both features.
What are your thoughts on these options?
AadithyaSai commentedon Oct 2, 2025
I beleive approach 3 would be the most ideal. 2 certainly has the most flexibility but adds an unnecessary level of complexity in my opinion. 3 would be idiomatically the most similar to what the github action currently does.
I believe, for 3 to work, however, the action would need to generate READMEs every time the PR is opened, reopened or synced instead of before the merge as i don't believe github provides any triggers that occur before the merge.
For the most part, mirroring the wiki content works just fine for README files. Having the ability to create a template README file would be very handy too.
As READMEs can contain other miscellaneous details about the module, I think allowing for README templates (such as how terraform-docs uses the inject feature) would be the best way to implement it, but keeping options to overwrite or skip it can be helpful too. It would add a layer of complexity for development though.
I don't believe it can replace wikis, after all wikis have a more robust sidebar and navigation experience compared to READMEs. There would be a fair degree of redundancy of information as well with both wikis and READMEs enabled so i think it is best to keep it as a feature flag that can be optionally disabled/enabled.
virgofx commentedon Oct 2, 2025
Super helpful, thanks for the response @AadithyaSai. There's a reason I never implemented this originally. Lots of considerations.
The ONLY downside I see is that if you end up working on a branch to do work in Terraform and then you push your branch, create a PR, and then the action automatically adds a new commit to update the README.md, and then you realized you missed something in your branch, one would then need to merge/rebase the latest changes before committing new local changes and pushing again (Since the origin would have a new github[bot] based commit on top).
That's the benefit of doing option # 1 - the downside, I don't think it's possible with github[bot] (requires PAT from another service account/user to handle issues where most repositories use branch protection/rulesets to block commits directly to default branch - which is what would have to happen in this case)
I'm wondering if there's any other way to do this cleanly
Edit: Another thought I had , we could do a hybrid of # 3 option as well where we create the commit in a new/temporary branch and on merge, a new PR get's created. This solves the issue of keeping ones local branch history clean; but introduces 2 PRs now for each terraform module change.
Maybe we provide both as separate options?
AadithyaSai commentedon Oct 3, 2025
You're right, the remote will have commits that are not in local, and will need to be synced again. I feel like the solution works fine though as ideally, devs wouldn't be editing the README manually and hence create conflicts.
method 1 works fine however if we can securely bypass the branch protection rules. Aside from PATs, it appears we could also use GitHub Apps or Deploy Tokens for bypassing branch protection as mentioned here.
The hybrid approach would create a lot of unnecessary PRs, which might trigger the Pull Request event and run the releaser pipeline unnecessarily, wasting action minutes on it. We'd need to implement a way to differentiate the automatically generated PRs from real PRs devs create.