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 Workflow

This action checks if the documentation is up-to-date for multiple GitHub Actions in a monorepo.

Inputs

Outputs

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