/ 
App-GHGen-0.05
River stage zero No dependents
/ README.md

NAME

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

VERSION

Version 0.05

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

REPOSITORY

https://github.com/nigelhorne/App-GHGen

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/nigelhorne/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: