/ 
App-GHGen-0.03
/ README.md

NAME

App::GHGen - Comprehensive GitHub Actions workflow generator, analyzer, and optimizer

SYNOPSIS

# Generate workflows
ghgen generate --auto                    # Auto-detect project type
ghgen generate --type=perl              # Generate Perl workflow
ghgen generate --type=perl --customize  # Interactive customization
ghgen generate --interactive            # Choose type interactively

# Analyze workflows
ghgen analyze                           # Analyze for issues
ghgen analyze --fix                     # Auto-fix issues
ghgen analyze --estimate                # Show cost estimates

# List available types
ghgen generate --list

DESCRIPTION

GHGen Workflow Analyzer is the all‑in‑one solution for keeping your GitHub Actions fast, secure, and effortlessly up‑to‑date. It automatically scans your workflows for performance bottlenecks, outdated actions, missing security permissions, and wasted CI minutes—then applies safe, intelligent fixes or opens a clean pull request with improvements. Whether you maintain a single project or dozens, GHGen saves time, reduces CI costs, and enforces modern best practices without manual effort. Developers choose it because it turns workflow maintenance from a chore into a fully automated, reliable part of their development pipeline.

Key Features

INSTALLATION

From CPAN

cpanm App::GHGen

From Source

git clone https://github.com/nigelhorne/App-GHGen.git
cd ghgen
cpanm --installdeps .
perl Makefile.PL
make
make test
make install

Quick Install Script

curl -L https://cpanmin.us | perl - App::GHGen

QUICK START

The fastest way to get started:

# Navigate to your project
cd my-project/

# Auto-detect and generate workflow
ghgen generate --auto

# Review the generated workflow
cat .github/workflows/*-ci.yml

# Commit and push
git add .github/workflows/
git commit -m "Add CI workflow"
git push

That's it! GHGen will detect your project type and create an optimized workflow.

WORKFLOW GENERATION

Auto-Detection

GHGen can automatically detect your project type by scanning for indicator files:

ghgen generate --auto

Detection looks for:

If multiple types are detected, it shows alternatives:

✓ Detected project type: PERL
  Evidence: cpanfile, lib, t

Other possibilities:
  • docker (confidence: 65%)

Generate PERL workflow? [Y/n]:

Specify Project Type

Generate for a specific language:

ghgen generate --type=perl
ghgen generate --type=node
ghgen generate --type=python
ghgen generate --type=rust
ghgen generate --type=go
ghgen generate --type=ruby
ghgen generate --type=docker
ghgen generate --type=static

Interactive Mode

Choose from a menu of available types:

ghgen generate --interactive

GitHub Actions Workflow Generator
==================================================

Select a project type:

  1. Node.js/npm
  2. Python
  3. Rust
  4. Go
  5. Ruby
  6. Perl
  7. Docker
  8. Static site (GitHub Pages)

Enter number (1-8):

Interactive Customization

Customize workflows with guided prompts:

ghgen generate --type=perl --customize

For Perl, you'll be asked:

Example session:

=== Workflow Customization: PERL ===

Perl Versions to Test:
Which Perl versions?
(Enter numbers separated by commas, or 'all')
  ✓ 1. 5.40
  ✓ 2. 5.38
  ✓ 3. 5.36
    4. 5.34
    5. 5.32

Enter choices [1,2,3]: 1,2,3

Operating Systems:
Which operating systems?
  ✓ 1. ubuntu-latest
  ✓ 2. macos-latest
  ✓ 3. windows-latest

Enter choices [1,2,3]: 1,2

Enable Perl::Critic? [Y/n]: y
Enable test coverage? [Y/n]: y

Each language has its own customization options appropriate to its ecosystem.

List Available Types

See all supported project types:

ghgen generate --list

Available workflow templates:

  node       - Node.js/npm projects with testing and linting
  python     - Python projects with pytest and coverage
  rust       - Rust projects with cargo, clippy, and formatting
  go         - Go projects with testing and race detection
  ruby       - Ruby projects with bundler and rake
  perl       - Perl projects with cpanm, prove, and coverage
  docker     - Docker image build and push workflow
  static     - Static site deployment to GitHub Pages

WORKFLOW ANALYSIS

Basic Analysis

Scan all workflows in your repository for issues:

ghgen analyze

GitHub Actions Workflow Analyzer
==================================================

📄 Analyzing: perl-ci.yml
  ⚠ No dependency caching found - increases build times
     💡 Fix:
     - uses: actions/cache@v5
       with:
         path: ~/perl5
         key: ${{ runner.os }}-${{ matrix.perl }}-${{ hashFiles('cpanfile') }}

  ⚠ Found 2 outdated action(s)
     💡 Fix:
     Update to latest versions:
       actions/cache@v4 → actions/cache@v5

==================================================
Summary:
  Workflows analyzed: 1
  Total issues found: 2

The analyzer checks for:

Auto-Fix

Automatically apply fixes to your workflows:

ghgen analyze --fix

GitHub Actions Workflow Analyzer
(Auto-fix mode enabled)
==================================================

📄 Analyzing: perl-ci.yml
  ⚙ Applying 3 fix(es)...
  ✓ Applied 3 fix(es)

==================================================
Summary:
  Workflows analyzed: 1
  Total issues found: 3
  Fixes applied: 3

Auto-fix can:

The auto-fix feature is safe:

Cost Estimation

See your current CI usage and potential savings:

ghgen analyze --estimate

GitHub Actions Workflow Analyzer
(Cost estimation mode)
==================================================

📊 Estimating current CI usage...

Current Monthly Usage:
  Total CI minutes: 1,247
  Billable minutes: 0 (after 2,000 free tier)
  Estimated cost: $0.00

Per-Workflow Breakdown:
  Perl CI      840 min/month (100 runs × 8.4 min/run)
  Node.js CI   300 min/month ( 60 runs × 5.0 min/run)
  Docker       107 min/month ( 20 runs × 5.4 min/run)

📄 Analyzing: node-ci.yml
  ⚠ No dependency caching found
  ⚠ No concurrency group defined

==================================================
Summary:
  Workflows analyzed: 3
  Total issues found: 2

💰 Potential Savings:
  With recommended changes: 647 CI minutes/month
  Reduction: -600 minutes (48%)
  Cost savings: $4.80/month (for private repos)

  Breakdown:
    • Adding dependency caching: ~75 min/month
    • Adding concurrency controls: ~525 min/month

The cost estimator considers:

GITHUB ACTION INTEGRATION

Use GHGen as a GitHub Action to analyze workflows automatically.

Mode 1: Comment on Pull Requests

Automatically comment on PRs that modify workflows:

# .github/workflows/ghgen-comment.yml
name: Analyze Workflows

on:
  pull_request:
    paths:
      - '.github/workflows/**'

permissions:
  contents: read
  pull-requests: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: nigelhorne/App-GHGen@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          mode: comment

This posts a comment like:

## 🔍 GHGen Workflow Analysis

| Category | Count | Auto-fixable |
|----------|-------|--------------|
| ⚡ Performance | 2 | 2 |
| 🔒 Security | 1 | 1 |

### 💰 Potential Savings
- ⏱️ Save **~650 CI minutes/month**
- 💵 Save **~$5/month** (private repos)

### 💡 How to Fix
Run locally: `ghgen analyze --fix`

Mode 2: Auto-Fix with Pull Request

Automatically create PRs with fixes on a schedule:

# .github/workflows/ghgen-autofix.yml
name: Weekly Workflow Optimization

on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9am UTC
  workflow_dispatch:     # Manual trigger

permissions:
  contents: write
  pull-requests: write

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: nigelhorne/App-GHGen@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          auto-fix: true
          create-pr: true

This creates a PR titled "🤖 Optimize GitHub Actions workflows" with all fixes applied.

Mode 3: CI Quality Gate

Fail builds if workflow issues are found:

# .github/workflows/ghgen-check.yml
name: Workflow Quality Check

on:
  pull_request:
    paths:
      - '.github/workflows/**'

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: nigelhorne/App-GHGen@v1
        id: check
      - name: Fail if issues found
        if: steps.check.outputs.issues-found > 0
        run: |
          echo "Found ${{ steps.check.outputs.issues-found }} issues"
          exit 1

SUPPORTED LANGUAGES

Perl

Comprehensive Perl testing with modern best practices.

Features:

Example:

ghgen generate --type=perl --customize

Generated workflow includes:

Node.js

Modern Node.js workflows with npm/yarn/pnpm support.

Features:

Customization options:

Python

Python testing with virtual environment support.

Features:

Rust

Rust workflows with cargo, clippy, and formatting.

Features:

Go

Go testing with modules and race detection.

Features:

Ruby

Ruby testing with Bundler integration.

Features:

Docker

Docker image building and publishing.

Features:

Static Sites

Static site deployment to GitHub Pages.

Features:

CONFIGURATION DETECTION

GHGen automatically detects configuration and adjusts workflows accordingly.

Minimum Version Detection

For Perl, minimum version is detected from:

Only compatible Perl versions are tested (e.g., if min is 5.36, won't test 5.32 or 5.34).

Dependency Files

Caching is based on dependency files:

BEST PRACTICES

Workflow Generation

Workflow Analysis

Cost Optimization

EXAMPLES

Example 1: New Perl Module

# In your new Perl module directory
cd My-Module/

# Create cpanfile
echo "requires 'perl', '5.036';" > cpanfile

# Auto-detect and generate
ghgen generate --auto

# Review and commit
cat .github/workflows/perl-ci.yml
git add .github/workflows/perl-ci.yml cpanfile
git commit -m "Add CI workflow"
git push

Example 2: Optimize Existing Project

# Clone project
git clone https://github.com/user/project.git
cd project/

# Analyze with cost estimation
ghgen analyze --estimate

# Review suggestions, then fix
ghgen analyze --fix

# Review changes
git diff .github/workflows/

# Commit improvements
git add .github/workflows/
git commit -m "Optimize CI: add caching, update actions, add permissions"
git push

Example 3: Multi-Language Project

# Project with both Node.js and Docker
cd fullstack-app/

# Generate Node.js workflow
ghgen generate --type=node --output=.github/workflows/frontend-ci.yml

# Generate Docker workflow
ghgen generate --type=docker --output=.github/workflows/backend-build.yml

# Analyze both
ghgen analyze

Example 4: Custom Perl Testing Matrix

# Interactive customization
ghgen generate --type=perl --customize

# Choose:
# Perl versions: 5.36, 5.38, 5.40 (skip older)
# OS: Ubuntu, macOS (skip Windows if not needed)
# Perl::Critic: Yes
# Coverage: Yes
# Branches: main

Example 5: CI Quality Gate

Add workflow quality checks to your CI:

# .github/workflows/ci-quality.yml
name: CI Quality Check

on:
  pull_request:
    paths:
      - '.github/workflows/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install GHGen
        run: cpanm --notest App::GHGen
      - name: Check workflows
        run: |
          if ! ghgen analyze; then
            echo "::error::Workflow quality issues found"
            echo "Run 'ghgen analyze --fix' locally to fix"
            exit 1
          fi

COMMAND REFERENCE

generate

ghgen generate [OPTIONS]

Generate a new GitHub Actions workflow.

Options:

Examples:

ghgen generate --auto
ghgen generate --type=perl --customize
ghgen generate --interactive
ghgen generate --type=node --output=custom.yml

analyze

ghgen analyze [OPTIONS]

Analyze existing workflows for issues and optimization opportunities.

Options:

Examples:

ghgen analyze
ghgen analyze --fix
ghgen analyze --estimate
ghgen analyze --fix --estimate

TROUBLESHOOTING

Installation Issues

Problem: cpanm fails to install dependencies

Solution:

# Install build tools first
# On Debian/Ubuntu:
sudo apt-get install build-essential

# On macOS:
xcode-select --install

# Then retry
cpanm App::GHGen

Generation Issues

Problem: "No .github/workflows directory"

Solution:

mkdir -p .github/workflows
ghgen generate --auto

Problem: Auto-detect doesn't find my project type

Solution:

# Specify type explicitly
ghgen generate --type=perl

# Or ensure indicator files exist
touch cpanfile  # for Perl
touch package.json  # for Node.js

Analysis Issues

Problem: "Failed to parse YAML"

Solution:

# Validate YAML syntax first
yamllint .github/workflows/*.yml

# Fix YAML errors, then retry
ghgen analyze

Problem: Cost estimates seem wrong

Solution:

Cost estimates are approximations based on:

Actual costs depend on your specific usage patterns.

Auto-Fix Issues

Problem: Auto-fix didn't fix everything

Solution:

Some issues can't be auto-fixed:

Review the remaining suggestions and apply manually.

GitHub Action Issues

Problem: "Permission denied" errors

Solution:

# Ensure correct permissions in workflow
permissions:
  contents: write        # For auto-fix
  pull-requests: write   # For comments

Problem: Action not triggering

Solution:

# For scheduled workflows, ensure:
on:
  schedule:
    - cron: '0 9 * * 1'
  workflow_dispatch:  # Allows manual trigger

# Test with manual trigger first

DEPENDENCIES

Runtime Dependencies

Test Dependencies

Optional Dependencies

SEE ALSO

GitHub Actions Documentation

CONTRIBUTING

Contributions are welcome! GHGen is open source and hosted on GitHub.

Ways to Contribute

Development Setup

# Fork and clone
git clone https://github.com/YOUR-USERNAME/ghgen.git
cd ghgen

# Install dependencies
cpanm --installdeps .

# Run tests
prove -lr t/

# Make changes
# ... edit files ...

# Test your changes
perl -Ilib bin/ghgen generate --type=perl
prove -lr t/

# Commit and push
git add .
git commit -m "Description of changes"
git push origin your-branch

# Open pull request on GitHub

Adding a New Language

To add support for a new language:

1. Create generator function in lib/App/GHGen/Generator.pm

2. Add detection logic in lib/App/GHGen/Detector.pm

3. Add customization in lib/App/GHGen/Interactive.pm

4. Add tests in t/

5. Update documentation

SUPPORT

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-app-ghgen at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-GHGen. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc App::GHGen

You can also look for information at:

Getting Help

Commercial Support

For commercial support, consulting, or custom development, contact the author.

AUTHOR

Nigel Horne njh@nigelhorne.com

https://github.com/nigelhorne

CONTRIBUTORS

Thanks to all contributors who have helped improve GHGen!

See https://github.com/nigelhorne/App-GHGen/graphs/contributors

COPYRIGHT AND LICENSE

Copyright 2025-2026 Nigel Horne.

Usage is subject to license terms.

The license terms of this software are as follows:

POD ERRORS

Hey! The above document had some coding errors, which are explained below: