Rebuilds README.md and associated banners from templates using the README.yaml metadata.
Note
This project is part of Cloud Posse's comprehensive "SweetOps" approach towards DevOps.
Learn More
It's 100% Open Source and licensed under the APACHE2.
We have dozens of GitHub Actions that are Open Source and well-maintained. Check them out!
This opinionated implementation builds upon Cloud Posse's build-harness and README.yaml used throughout Cloud Posse's GitHub repositories.
Important
In Cloud Posse's examples, we avoid pinning GitHub Actions to specific versions to prevent discrepancies between the documentation and the latest released versions. However, for your own projects, we strongly advise pinning each GitHub Action to the exact version you're using. This practice ensures the stability of your workflows. Additionally, we recommend implementing a systematic approach for updating versions to avoid unexpected changes.
To use this project, follow these steps:
Add the following code to your workflow file (e.g., .github/workflows/readme.yml):
name: READMEon:
pull_request:
branches: [ 'main' ]types: [opened, synchronize, reopened, closed, labeled, unlabeled]jobs:
generate:
runs-on: ubuntu-lateststeps:
- name: Rebuild README.md and Banneruses: cloudposse-github-actions/readme@v0id: readmewith:
banner_enabled: truereadme_enabled: trueoutputs:
banner_file: ${{ steps.readme.outputs.banner_file }}readme_file: ${{ steps.readme.outputs.readme_file }}In the following example, we use the workflow_dispatch event to allow manual triggering of the workflow to rebuild the readme.
We also use the pull_request event to register the workflow from the PR. This allows us to test the workflow before merging
it to the main branch.
name: READMEon:
# Allow manual triggering of workflow to rebuild readmeworkflow_dispatch: {}## Added pull_request to register workflow from the PR.## Read more https://stackoverflow.com/questions/63362126/github-actions-how-to-run-a-workflow-created-on-a-non-master-branch-from-the-wopull_request:
branches-ignore: ['*']schedule:
# Update README.md nightly at 4am UTC# .---------------- minute (0 - 59)# | .------------- hour (0 - 23)# | | .---------- day of month (1 - 31)# | | | .------- month (1 - 12) OR jan,feb,mar,apr ...# | | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat# | | | | |
- cron: '0 4 * * *'jobs:
generate:
runs-on: ubuntu-lateststeps:
- name: Rebuild README.md and Banneruses: cloudposse-github-actions/readme@v0id: readmewith:
banner_enabled: truereadme_enabled: truev1 use atmos instead of build-harness.
You can drop Makefile if you use it only for readme generation.
To support atmos reaadme generation, you must create atmos.yaml config.
The configuration depends on your repo - please follow this documentation
Example:
docs:
generate:
readme:
base-dir: .input:
- "./README.yaml"template: "https://.../README.md.gotmpl"output: "./README.md"terraform:
source: src/enabled: falseformat: "markdown"show_providers: falseshow_inputs: trueshow_outputs: truesort_by: "name"hide_empty: falseindent_level: 2| Name | Description | Default | Required |
|---|---|---|---|
| atmos-version | The version of atmos to install | >= 1.175.0 | false |
| banner_enabled | Enable banner generation | true | false |
| command | Atmos command to generate readme | docs generate readme | true |
| commit_author | The author to use when committing changes. | readme-action 📖 actions@github.com | false |
| commit_message | The commit message to use when committing changes. | chore: update README.md | false |
| commit_method | The method to apply changes. Can be either 'commit' or 'pr'. | commit | true |
| commit_push_options | The push options to use when committing changes. Use --force-with-lease to avoid overwriting changes when pushing to a protected branch using admin or bypass privileges. See https://git-scm.com/docs/git-push#\_options for more. | false | |
| commit_user_email | The user email to use when committing changes. | actions@github.com | false |
| commit_user_name | The user name to use when committing changes. | readme-action 📖 | false |
| pr_base_branch | Repo default base-branch for Pull Requests (when commit_method: pr) | false | |
| pr_branch | Branch to create Pull Requests from (when commit_method: pr). Suggest using a protected branch for auto-merge capabilities. | auto-update/readme | false |
| pr_labels | Whitespace-separated list of labels to apply to Pull Requests (when commit_method: pr or ( commit_method: commit and github context is a PR) )) | auto-update no-release readme | false |
| pr_title | The title to use when creating a Pull Request (when commit_method: pr) | Update README.md and docs | false |
| readme_enabled | Enable README generation | true | false |
| repository_description | GitHub repository description | false | |
| repository_name | GitHub repository name in the repository\_org that hosts the banner templates | false | |
| repository_org | GitHub organization or user name used for the banner templates | false | |
| sign-commits | Sign commits for pr commit_method as github-actions[bot] when using GITHUB\_TOKEN, or your own bot when using GitHub App tokens. | false | false |
| token | GitHub API token (use a PAT if you need to trigger other actions) | ${{ github.token }} | false |
| validate_readme | Validate the README.md file using markdown-link-check | true | false |
| Name | Description |
|---|---|
| banner_file | Generated banner file path (if banner_enabled: true) |
| changes_detected | Changes detected |
| readme_file | Generated README file path (if readme_enabled: true) |
Check out these related projects.
For additional context, refer to some of these links.
This project is under active development, and we encourage contributions from our community. Many thanks to our outstanding contributors:
Please use the issue tracker to report any bugs or file feature requests.
If you are interested in being a contributor and want to get involved in developing this project or help out with Cloud Posse's other projects, we would love to hear from you!
Hit us up in Slack, in the #cloudposse channel.
In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
- Review our Code of Conduct and Contributor Guidelines.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull Request so that we can review your changes
NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!
Join our Open Source Community on Slack. It's FREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally sweet infrastructure.
Sign up for our newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know. Dropped straight into your Inbox every week — and usually a 5-minute read.
Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and GitHub Action insights, all sourced from our SweetOps community, plus a live Q&A that you can’t find anywhere else. It's FREE for everyone!
This project is maintained by Cloud Posse, LLC.
We are a DevOps Accelerator for funded startups and enterprises. Use our ready-to-go terraform architecture blueprints for AWS & GitHub Actions to get up and running quickly. We build it with you. You own everything. Your team wins. Plus, we stick around until you succeed.
Your team can operate like a pro today.
Ensure that your team succeeds by using our proven process and turnkey blueprints. Plus, we stick around until you succeed.
📚 See What's Included
- Reference Architecture. You'll get everything you need from the ground up built using 100% infrastructure as code.
- Deployment Strategy. You'll have a battle-tested deployment strategy using GitHub Actions that's automated and repeatable.
- Site Reliability Engineering. You'll have total visibility into your apps and microservices.
- Security Baseline. You'll have built-in governance with accountability and audit logs for all changes.
- GitOps. You'll be able to operate your infrastructure via Pull Requests.
- Training. You'll receive hands-on training so your team can operate what we build.
- Questions. You'll have a direct line of communication between our teams via a Shared Slack channel.
- Troubleshooting. You'll get help to triage when things aren't working.
- Code Reviews. You'll receive constructive feedback on Pull Requests.
- Bug Fixes. We'll rapidly work with you to fix any bugs in our projects.
Preamble to the Apache License, Version 2.0
Complete license is available in the LICENSE file.
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
Copyright © 2017-2025 Cloud Posse, LLC