gh-action-readme

gh-action-readme

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 documentation for more information.

Prerequisites

• GitHub CLI installed and authenticated.

⚡️ Quick Start

Install the gh-action-readme extension

The gh-action-readme extension can be installed using the following command.

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.

# <!--name--><!--/name-->
<!--description-->

## Inputs
<!--inputs-->

Update the README.md file

Run the following command to update the README.md file with the metadata from the action.yml file.

gh action-readme update

That's it! 🎉

The README.md file will be updated with the metadata from the action.yml file.

-# <!--name--><!--/name-->
+# <!--name-->Awesome Action<!--/name-->
<!--description-->
+A GitHub Action that does something awesome.
+Something that is very useful.
+<!--/description-->

## Inputs
<!--inputs-->
+| Name   | Description     | Required | Default   |
+|--------|-----------------|----------|-----------|
+| input1 | The first input | `true`   | `default` |
+<!--/inputs-->

Checkout the documentation for more information on how to use the gh-action-readme extension.

• Getting Started - Quick start tutorial (5 minutes)
• Building a Complete Action README - Full example with all features
• Set up pre-commit hooks - Automatically update READMEs on commit
• Manage monorepos with multiple actions - Bulk operations on multiple actions
• Check for documentation drift - 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 hook to automatically update the README.md file before committing changes.

Add the following configuration to the .pre-commit-config.yaml file.

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.

pre-commit install

[!TIP] You can use the pre-commit action to run the pre-commit checks in your GitHub Actions workflow.

GitHub Actions Monorepo Support

The action-readme pre-commit supports monorepos with multiple actions in a single repository. It will automatically detect the action.yml files in the repository and update the corresponding README.md files.

.
├── action-a/
│   ├── action.yml
│   └── README.md
├── action-b/
│   ├── action.yml
│   └── README.md
└── some/
    └── folder/
        └── action-c/
            ├── action.yml
            └── README.md