gh-action-readme

The definitive CLI tool for generating beautiful documentation from GitHub Actions action.yml files

Transform your GitHub Actions into professional documentation with multiple themes, output formats, and enterprise-grade features.

✨ Features

🎨 5 Beautiful Themes - GitHub, GitLab, Minimal, Professional, Default 📄 4 Output Formats - Markdown, HTML, JSON, AsciiDoc 🎯 Smart Validation - Context-aware suggestions for fixing action.yml files 🚀 Modern CLI - Colored output, progress bars, comprehensive help ⚙️ Enterprise Ready - XDG-compliant configuration, recursive processing 🔧 Developer Friendly - Template customization, batch operations 📁 Flexible Targeting - Directory/file arguments, custom output filenames 🛡️ Thread Safe - Race condition protection, concurrent processing ready

🚀 Quick Start

Installation

📦 Binary Releases (Recommended)

Download pre-built binaries for your platform:

# Linux x86_64
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Linux_x86_64.tar.gz | tar -xz

# macOS x86_64 (Intel)
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_x86_64.tar.gz | tar -xz

# macOS ARM64 (Apple Silicon)
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_arm64.tar.gz | tar -xz

# Windows x86_64 (PowerShell)
Invoke-WebRequest -Uri "https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Windows_x86_64.zip" -OutFile "gh-action-readme.zip"
Expand-Archive gh-action-readme.zip

🍺 Package Managers

# macOS with Homebrew
brew install ivuorinen/tap/gh-action-readme

# Windows with Scoop
scoop bucket add ivuorinen https://github.com/ivuorinen/scoop-bucket
scoop install gh-action-readme

# Using Go
go install github.com/ivuorinen/gh-action-readme@latest

🐳 Docker

# Run directly with Docker
docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:latest gen

# Or use as base image
FROM ghcr.io/ivuorinen/gh-action-readme:latest

🔨 Build from Source

git clone https://github.com/ivuorinen/gh-action-readme.git
cd gh-action-readme
go build .

Basic Usage

# Generate README.md from action.yml in current directory
gh-action-readme gen

# Target specific directories or files
gh-action-readme gen testdata/example-action/
gh-action-readme gen testdata/composite-action/action.yml

# Use GitHub theme with custom output filename
gh-action-readme gen --theme github --output custom-readme.md

# Generate JSON for API integration with custom filename
gh-action-readme gen --output-format json --output api-docs.json

# Process all action.yml files recursively
gh-action-readme gen --recursive --theme professional

📋 Examples

Input: action.yml

name: My Action
description: Does something awesome
inputs:
  token:
    description: GitHub token
    required: true
  environment:
    description: Target environment
    default: production
outputs:
  result:
    description: Action result
runs:
  using: node20
  main: index.js

Output: Professional README.md

The tool generates comprehensive documentation including:

• 📊 Parameter tables with types, requirements, defaults
• 💡 Usage examples with proper YAML formatting
• 🎨 Badges for marketplace visibility
• 📚 Multiple sections (Overview, Configuration, Examples, Troubleshooting)
• 🔗 Navigation with table of contents

🎨 Themes

Theme	Description	Best For
github	Badges, tables, collapsible sections	GitHub marketplace
gitlab	GitLab CI/CD focused examples	GitLab repositories
minimal	Clean, concise documentation	Simple actions
professional	Comprehensive with troubleshooting	Enterprise use
default	Original simple template	Basic needs

📄 Output Formats

Format	Description	Use Case
md	Markdown (default)	GitHub README files
html	Styled HTML	Web documentation
json	Structured data	API integration
asciidoc	AsciiDoc format	Technical docs

🛠️ Commands

Generation

gh-action-readme gen [directory_or_file] [flags]
  -f, --output-format string   md, html, json, asciidoc (default "md")
  -o, --output-dir string      output directory (default ".")
      --output string          custom output filename
  -t, --theme string           github, gitlab, minimal, professional
  -r, --recursive              search recursively

Validation

gh-action-readme validate
# Validates action.yml files with helpful suggestions

Configuration

gh-action-readme config init     # Create default config
gh-action-readme config show     # Show current settings
gh-action-readme config themes   # List available themes
gh-action-readme config wizard   # Interactive configuration wizard

⚙️ Configuration

Create persistent settings with XDG-compliant configuration:

gh-action-readme config init

Configuration file (~/.config/gh-action-readme/config.yaml):

theme: github
output_format: md
output_dir: .
verbose: false

Environment Variables:

export GH_ACTION_README_THEME=github
export GH_ACTION_README_VERBOSE=true

🎯 Advanced Usage

Batch Processing

# Process multiple repositories with custom outputs
find . -name "action.yml" -execdir gh-action-readme gen --theme github --output README-generated.md \;

# Recursive processing with JSON output and custom directory structure
gh-action-readme gen --recursive --output-format json --output-dir docs/

# Target multiple specific actions with different themes
gh-action-readme gen actions/checkout/ --theme github --output docs/checkout.md
gh-action-readme gen actions/setup-node/ --theme professional --output docs/setup-node.md

Custom Themes

# Copy and modify existing theme
cp -r templates/themes/github templates/themes/custom
# Edit templates/themes/custom/readme.tmpl
gh-action-readme gen --theme custom

Validation with Suggestions

gh-action-readme validate --verbose
# ❌ Missing required field: description
# 💡 Add 'description: Brief description of what your action does'

🏗️ Development

Prerequisites

• Go 1.22+
• golangci-lint

Build

go build .
go test ./internal
golangci-lint run

Code Quality

This project maintains high code quality standards:

• ✅ 0 linting violations - Clean, maintainable codebase
• ✅ Comprehensive test coverage - 80%+ coverage across critical modules
• ✅ Low cyclomatic complexity - All functions under 10 complexity
• ✅ Minimal code duplication - Shared utilities and helper functions
• ✅ Proper error handling - All errors properly acknowledged and handled
• ✅ Standardized formatting - gofmt and goimports applied consistently

Recent Improvements (August 6, 2025):

• Enhanced Gen Command: Added directory/file targeting with --output flag for custom filenames
• Thread Safety: Implemented RWMutex synchronization for race condition protection
• GitHub Actions Integration: Enhanced CI workflow showcasing all new gen command features
• Code Quality: Achieved zero linting violations with complete EditorConfig compliance
• Architecture: Added contextual error handling, interactive wizard, and progress indicators

Testing

# Test generation (safe - uses testdata/)
gh-action-readme gen testdata/example-action/ --theme github --output test-output.md
gh-action-readme gen testdata/composite-action/action.yml --theme professional

# Run full test suite
go test ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

🔒 Security

gh-action-readme follows security best practices with comprehensive vulnerability scanning and protection measures:

Automated Security Scanning

• govulncheck: Go-specific vulnerability detection
• Snyk: Dependency vulnerability analysis
• Trivy: Container and filesystem security scanning
• gitleaks: Secrets detection and prevention
• CodeQL: Static code analysis for security issues
• Dependabot: Automated dependency updates

Local Security Testing

# Run all security scans
make security

# Individual security checks
make vulncheck  # Go vulnerability scanning
make snyk       # Dependency analysis
make trivy      # Filesystem scanning
make gitleaks   # Secrets detection
make audit      # Comprehensive security audit

Security Policy

For reporting security vulnerabilities, please see our Security Policy.

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md.

Quick Start:

1. Fork the repository
2. Create a feature branch
3. Make changes (see CLAUDE.md for development guide)
4. Add tests
5. Submit pull request

📊 Comparison

Feature	gh-action-readme	action-docs	gh-actions-auto-docs
Themes	5 themes	1 basic	1 basic
Output Formats	4 formats	1 format	1 format
Validation	Smart suggestions	Basic	None
Configuration	XDG compliant	None	Basic
CLI UX	Modern + colors	Basic	Basic
Templates	Customizable	Fixed	Fixed

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Cobra for CLI framework
• Viper for configuration management
• GitHub Actions community for inspiration

---

_{Built with ❤️ by ivuorinen}