https://github.com/reakaleek/gh-action-readme
A GitHub CLI extension to generate and update GitHub Action docs
https://github.com/reakaleek/gh-action-readme
gh-extension github-actions markdown
Last synced: 2 months ago
JSON representation
A GitHub CLI extension to generate and update GitHub Action docs
- Host: GitHub
- URL: https://github.com/reakaleek/gh-action-readme
- Owner: reakaleek
- License: mit
- Created: 2024-05-27T10:58:43.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-13T16:37:34.000Z (about 2 years ago)
- Last Synced: 2025-08-21T07:13:04.658Z (10 months ago)
- Topics: gh-extension, github-actions, markdown
- Language: Go
- Homepage:
- Size: 35.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gh-action-readme
[](https://github.com/reakaleek/gh-action-readme/actions/workflows/ci.yml)
A GitHub CLI extension to inject GitHub Actions metadata into `README.md` markdown files.
> [!TIP]
> Do you need to manage multiple actions in a github-actions monorepo? Check out the [How to Manage Monorepos with Multiple Actions](./docs/how-to/manage-monorepos.md) documentation for more information.
## Prerequisites
- [GitHub CLI](https://cli.github.com/) installed and authenticated.
## ⚡️ Quick Start
### Install the gh-action-readme extension
The `gh-action-readme` extension can be installed using the following command.
```bash
gh extension install reakaleek/gh-action-readme
```
### Create a README.md file
Create a `README.md` file in the action directory containing the `action.yml` file.
You can use the following template to define the metadata placeholders.
```markdown
#
## Inputs
```
### Update the `README.md` file
Run the following command to update the `README.md` file with the metadata from the `action.yml` file.
```bash
gh action-readme update
```
### That's it! 🎉
The `README.md` file will be updated with the metadata from the `action.yml` file.
```diff
-#
+# Awesome Action
+A GitHub Action that does something awesome.
+Something that is very useful.
+
## Inputs
+| Name | Description | Required | Default |
+|--------|-----------------|----------|-----------|
+| input1 | The first input | `true` | `default` |
+
```
Checkout the documentation for more information on how to use the `gh-action-readme` extension.
- [Getting Started](./docs/tutorials/getting-started.md) - Quick start tutorial (5 minutes)
- [Building a Complete Action README](./docs/tutorials/complete-action-readme.md) - Full example with all features
- [Set up pre-commit hooks](./docs/how-to/setup-precommit.md) - Automatically update READMEs on commit
- [Manage monorepos with multiple actions](./docs/how-to/manage-monorepos.md) - Bulk operations on multiple actions
- [Check for documentation drift](./docs/how-to/check-documentation-drift.md) - Verify docs are up-to-date
## Pre-commit (recommended)
> [!NOTE]
> Using gh-action-readme as a pre-commit hook does not require
> you to install the `gh-action-readme` extension in github cli.
You can also use the `gh-action-readme` extension as a [pre-commit](https://pre-commit.com/) hook to automatically update the `README.md` file before committing changes.
Add the following configuration to the `.pre-commit-config.yaml` file.
```yaml
repos:
- repo: https://github.com/reakaleek/gh-action-readme
rev: v0.5.0
hooks:
- id: action-readme
```
Then run the following command to install the pre-commit hook.
```bash
pre-commit install
```
> [!TIP]
> You can use the [pre-commit action](https://github.com/marketplace/actions/pre-commit) to run the pre-commit checks in your GitHub Actions workflow.
## GitHub Actions Workflow
This action checks if the documentation is up-to-date for multiple GitHub Actions in a monorepo.
### Inputs
| Name | Description | Required | Default |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-----------------------|
| `version` | Use a specific version of gh-action-readme (e.g. v0.5.0). You can find the latest version at https://github.com/reakaleek/gh-action-readme/releases. | `false` | ` ` |
| `github-token` | A GitHub token with permissions to install extensions. | `false` | `${{ github.token }}` |
| `command` | The gh-action-readme command to run. | `false` | `diff` |
| `args` | Arguments to pass to the command. | `false` | `--recursive` |
### Outputs
| Name | Description |
|------|-------------|
```yaml
name: Check README.md
on:
pull_request:
paths:
- '**/action.yml'
- '**/README.md'
jobs:
gh-actions-readme-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: reakaleek/gh-action-readme@v1
```