blib/lib/App/GHGen.pm

filter: Statementstmt 100% 10 / 10 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 100% 13 / 13 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« lib/App/GHGen/Generator.pm ↑ Summary
1 package App::GHGen;
2  
3 # Try this to update GitHub Marketplace release, but bear in mind it tends to not work, marketplace does not detect the update
4 # Update the @v1 to @v2 in action.yml
5 # git tag -a v2 -m 'Release v0.02'
6 # git push origin v2
7 # Go to https://github.com/nigelhorne/App-GHGen/releases
8 # Click 'Draft a new release'
9 # Choose the new tag: v2
10 # Commit release v2
11 # Publish the release
12  
13 1 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 =head1 NAME
18  
19 App::GHGen - GitHub Actions workflow generator, analyzer, and optimizer
20  
21 =head1 VERSION
22  
23 Version 0.12
24  
25 =cut
26  
27 1 our $VERSION = '0.12';
28  
29 =head1 SYNOPSIS
30  
31 # Generate workflows
32 ghgen generate --auto # Auto-detect project type
33 ghgen generate --type=perl # Generate Perl workflow
34 ghgen generate --type=perl --customize # Interactive customization
35 ghgen generate --interactive # Choose type interactively
36  
37 # Analyze workflows
38 ghgen analyze # Analyze for issues
39 ghgen analyze --fix # Auto-fix issues
40 ghgen analyze --estimate # Show cost estimates
41  
42 # List available types
43 ghgen generate --list
44  
45 =head1 DESCRIPTION
46  
47 GHGen Workflow Analyzer is the all-in-one solution for keeping your GitHub Actions fast,
48 secure, and effortlessly up-to-date.
49 It automatically scans your workflows for performance bottlenecks,
50 outdated actions,
51 missing security permissions, and wasted CI minutes-then applies safe, intelligent fixes or opens a clean pull request with improvements.
52 Whether you maintain a single project or dozens,
53 GHGen saves time, reduces CI costs, and enforces modern best practices without manual effort.
54 Developers choose it because it turns workflow maintenance from a chore into a fully automated,
55 reliable part of their development pipeline.
56  
57 =head2 Key Features
58  
59 =encoding utf-8
60  
61 =over 4
62  
63 =item * B<Auto-detect project type> - Intelligently scans your repository to detect language and dependencies
64  
65 =item * B<Generate optimized workflows> - Creates workflows with caching, security, concurrency, and best practices built-in
66  
67 =item * B<Analyze existing workflows> - Comprehensive analysis for performance, security, cost, and maintenance issues
68  
69 =item * B<Auto-fix issues> - Automatically applies fixes for detected problems (adds caching, updates versions, adds permissions, etc.)
70  
71 =item * B<Interactive customization> - Guided workflow creation with smart defaults and multi-select options
72  
73 =item * B<Cost estimation> - Estimates current CI minutes usage and calculates potential savings from optimizations
74  
75 =item * B<GitHub Action integration> - Run as a GitHub Action to analyze PRs, comment with suggestions, and create fix PRs
76  
77 =item * B<Per-workflow breakdown> - Detailed analysis of each workflow's cost and optimization potential
78  
79 =back
80  
81 =head1 INSTALLATION
82  
83 =head2 From CPAN
84  
85 cpanm App::GHGen
86  
87 =head2 From Source
88  
89 git clone https://github.com/nigelhorne/App-GHGen.git
90 cd ghgen
91 cpanm --installdeps .
92 perl Makefile.PL
93 make
94 make test
95 make install
96  
97 =head2 Quick Install Script
98  
99 curl -L https://cpanmin.us | perl - App::GHGen
100  
101 =head1 QUICK START
102  
103 The fastest way to get started:
104  
105 # Navigate to your project
106 cd my-project/
107  
108 # Auto-detect and generate workflow
109 ghgen generate --auto
110  
111 # Review the generated workflow
112 cat .github/workflows/*-ci.yml
113  
114 # Commit and push
115 git add .github/workflows/
116 git commit -m "Add CI workflow"
117 git push
118  
119 That's it! GHGen will detect your project type and create an optimized workflow.
120  
121 =head1 WORKFLOW GENERATION
122  
123 =head2 Auto-Detection
124  
125 GHGen can automatically detect your project type by scanning for indicator files:
126  
127 ghgen generate --auto
128  
129 Detection looks for:
130  
131 =over 4
132  
133 =item * B<Perl>: cpanfile, dist.ini, Makefile.PL, Build.PL, lib/*.pm
134  
135 =item * B<Node.js>: package.json, package-lock.json, yarn.lock
136  
137 =item * B<Python>: requirements.txt, setup.py, pyproject.toml
138  
139 =item * B<Rust>: Cargo.toml, Cargo.lock
140  
141 =item * B<Go>: go.mod, go.sum
142  
143 =item * B<Ruby>: Gemfile, Rakefile
144  
145 =item * B<Docker>: Dockerfile, docker-compose.yml
146  
147 =back
148  
149 If multiple types are detected, it shows alternatives:
150  
151 ✓ Detected project type: PERL
152 Evidence: cpanfile, lib, t
153  
154 Other possibilities:
155 • docker (confidence: 65%)
156  
157 Generate PERL workflow? [Y/n]:
158  
159 =head2 Specify Project Type
160  
161 Generate for a specific language:
162  
163 ghgen generate --type=perl
164 ghgen generate --type=node
165 ghgen generate --type=python
166 ghgen generate --type=rust
167 ghgen generate --type=go
168 ghgen generate --type=ruby
169 ghgen generate --type=docker
170 ghgen generate --type=static
171  
172 =head2 Interactive Mode
173  
174 Choose from a menu of available types:
175  
176 ghgen generate --interactive
177  
178 GitHub Actions Workflow Generator
179 ==================================================
180  
181 Select a project type:
182  
183 1. Node.js/npm
184 2. Python
185 3. Rust
186 4. Go
187 5. Ruby
188 6. Perl
189 7. Docker
190 8. Static site (GitHub Pages)
191  
192 Enter number (1-8):
193  
194 =head2 Interactive Customization
195  
196 Customize workflows with guided prompts:
197  
198 ghgen generate --type=perl --customize
199  
200 For Perl, you'll be asked:
201  
202 =over 4
203  
204 =item * B<Perl versions to test> - Select from 5.22 through 5.42 (multi-select with defaults)
205  
206 =item * B<Operating systems> - Ubuntu, macOS, Windows (multi-select)
207  
208 =item * B<Enable syntax linting> - C<perl -c> check on all C<.pm> files, run across every matrix cell; requires no extra CPAN modules (yes/no, default: yes)
209  
210 =item * B<Enable unused-variable check> - C<warnings::unused> check, latest Perl + Ubuntu only (yes/no, default: no)
211  
212 =item * B<Enable Perl::Critic> - Code quality analysis, latest Perl + Ubuntu only (yes/no, default: yes)
213  
214 =item * B<Enable Devel::Cover> - Test coverage, latest Perl + Ubuntu only (yes/no, default: yes)
215  
216 =item * B<Branch configuration> - Which branches to run on
217  
218 =back
219  
220 Example session:
221  
222 === Workflow Customization: PERL ===
223  
224 Perl Versions to Test:
225 Which Perl versions?
226 (Enter numbers separated by commas, or 'all')
227 ✓ 1. 5.40
228 ✓ 2. 5.38
229 ✓ 3. 5.36
230 4. 5.34
231 5. 5.32
232  
233 Enter choices [1,2,3]: 1,2,3
234  
235 Operating Systems:
236 Which operating systems?
237 ✓ 1. ubuntu-latest
238 ✓ 2. macos-latest
239 ✓ 3. windows-latest
240  
241 Enter choices [1,2,3]: 1,2
242  
243 Code Quality Tools:
244 Enable syntax linting (perl -c on all matrix cells)? [Y/n]: y
245  
246 Enable unused-variable check (warnings::unused, latest+ubuntu only)? [y/N]: n
247  
248 Enable Perl::Critic? [Y/n]: y
249 Enable test coverage? [Y/n]: y
250  
251 Each language has its own customization options appropriate to its ecosystem.
252  
253 =head2 List Available Types
254  
255 See all supported project types:
256  
257 ghgen generate --list
258  
259 Available workflow templates:
260  
261 node - Node.js/npm projects with testing and linting
262 python - Python projects with pytest and coverage
263 rust - Rust projects with cargo, clippy, and formatting
264 go - Go projects with testing and race detection
265 ruby - Ruby projects with bundler and rake
266 perl - Perl projects with cpanm, prove, and coverage
267 docker - Docker image build and push workflow
268 static - Static site deployment to GitHub Pages
269  
270 =head1 WORKFLOW ANALYSIS
271  
272 =head2 Basic Analysis
273  
274 Scan all workflows in your repository for issues:
275  
276 ghgen analyze
277  
278 GitHub Actions Workflow Analyzer
279 ==================================================
280  
281 📄 Analyzing: perl-ci.yml
282 ⚠ No dependency caching found - increases build times
283 💡 Fix:
284 - uses: actions/cache@v5
285 with:
286 path: ~/perl5
287 key: ${{ runner.os }}-${{ matrix.perl }}-${{ hashFiles('cpanfile') }}
288  
289 ⚠ Found 2 outdated action(s)
290 💡 Fix:
291 Update to latest versions:
292 actions/cache@v4 → actions/cache@v5
293  
294 ==================================================
295 Summary:
296 Workflows analyzed: 1
297 Total issues found: 2
298  
299 The analyzer checks for:
300  
301 =over 4
302  
303 =item * B<Performance Issues>
304  
305 =over 8
306  
307 =item - Missing dependency caching (npm, pip, cargo, go, bundler, cpanm)
308  
309 =item - Jobs that could run in parallel
310  
311 =back
312  
313 =item * B<Security Issues>
314  
315 =over 8
316  
317 =item - Unpinned action versions (@master, @main)
318  
319 =item - Missing permissions declarations
320  
321 =item - Overly broad permissions (contents: write when read is sufficient)
322  
323 =back
324  
325 =item * B<Cost Issues>
326  
327 =over 8
328  
329 =item - Missing concurrency controls (wasted CI on superseded runs)
330  
331 =item - Overly broad triggers (runs on every push without filters)
332  
333 =item - Inefficient matrix strategies
334  
335 =back
336  
337 =item * B<Maintenance Issues>
338  
339 =over 8
340  
341 =item - Outdated action versions (v4 → v5, v5 → v6)
342  
343 =item - Outdated runner versions (ubuntu-18.04 → ubuntu-latest)
344  
345 =back
346  
347 =back
348  
349 =head2 Auto-Fix
350  
351 Automatically apply fixes to your workflows:
352  
353 ghgen analyze --fix
354  
355 GitHub Actions Workflow Analyzer
356 (Auto-fix mode enabled)
357 ==================================================
358  
359 📄 Analyzing: perl-ci.yml
360 ⚙ Applying 3 fix(es)...
361 ✓ Applied 3 fix(es)
362  
363 ==================================================
364 Summary:
365 Workflows analyzed: 1
366 Total issues found: 3
367 Fixes applied: 3
368  
369 Auto-fix can:
370  
371 =over 4
372  
373 =item * B<Add caching> - Detects project type and adds appropriate dependency caching
374  
375 =item * B<Update actions> - Updates to latest versions (cache@v4→v5, checkout@v5→v6, etc.)
376  
377 =item * B<Pin versions> - Converts @master/@main to specific version tags
378  
379 =item * B<Add permissions> - Adds C<permissions: contents: read> for security
380  
381 =item * B<Add concurrency> - Adds concurrency groups to cancel superseded runs
382  
383 =item * B<Optimize triggers> - Adds branch and path filters
384  
385 =item * B<Update runners> - Changes ubuntu-18.04 to ubuntu-latest
386  
387 =back
388  
389 The auto-fix feature is safe:
390  
391 =over 4
392  
393 =item * Only fixes well-understood issues
394  
395 =item * Preserves YAML structure and comments
396  
397 =item * Changes are easily reviewable with C<git diff>
398  
399 =item * Can be reverted if needed
400  
401 =back
402  
403 =head2 Cost Estimation
404  
405 See your current CI usage and potential savings:
406  
407 ghgen analyze --estimate
408  
409 GitHub Actions Workflow Analyzer
410 (Cost estimation mode)
411 ==================================================
412  
413 📊 Estimating current CI usage...
414  
415 Current Monthly Usage:
416 Total CI minutes: 1,247
417 Billable minutes: 0 (after 2,000 free tier)
418 Estimated cost: $0.00
419  
420 Per-Workflow Breakdown:
421 Perl CI 840 min/month (100 runs × 8.4 min/run)
422 Node.js CI 300 min/month ( 60 runs × 5.0 min/run)
423 Docker 107 min/month ( 20 runs × 5.4 min/run)
424  
425 📄 Analyzing: node-ci.yml
426 ⚠ No dependency caching found
427 ⚠ No concurrency group defined
428  
429 ==================================================
430 Summary:
431 Workflows analyzed: 3
432 Total issues found: 2
433  
434 💰 Potential Savings:
435 With recommended changes: 647 CI minutes/month
436 Reduction: -600 minutes (48%)
437 Cost savings: $4.80/month (for private repos)
438  
439 Breakdown:
440 • Adding dependency caching: ~75 min/month
441 • Adding concurrency controls: ~525 min/month
442  
443 The cost estimator considers:
444  
445 =over 4
446  
447 =item * Workflow trigger frequency (push, PR, schedule)
448  
449 =item * Estimated duration per run (based on steps and commands)
450  
451 =item * Matrix build multipliers (e.g., 3 OS × 8 Perl versions = 24 jobs)
452  
453 =item * Parallel vs sequential job execution
454  
455 =item * GitHub Actions pricing ($0.008/minute for private repos, 2000 free minutes/month)
456  
457 =back
458  
459 =head1 GITHUB ACTION INTEGRATION
460  
461 Use GHGen as a GitHub Action to analyze workflows automatically.
462  
463 =head2 Mode 1: Comment on Pull Requests
464  
465 Automatically comment on PRs that modify workflows:
466  
467 # .github/workflows/ghgen-comment.yml
468 name: Analyze Workflows
469  
470 on:
471 pull_request:
472 paths:
473 - '.github/workflows/**'
474  
475 permissions:
476 contents: read
477 pull-requests: write
478  
479 jobs:
480 analyze:
481 runs-on: ubuntu-latest
482 steps:
483 - uses: actions/checkout@v6
484 - uses: nigelhorne/App-GHGen@v1
485 with:
486 github-token: ${{ secrets.GITHUB_TOKEN }}
487 mode: comment
488  
489 This posts a comment like:
490  
491 ## 🔍 GHGen Workflow Analysis
492  
493 | Category | Count | Auto-fixable |
494 |----------|-------|--------------|
495 | ⚡ Performance | 2 | 2 |
496 | 🔒 Security | 1 | 1 |
497  
498 ### 💰 Potential Savings
499 - ⏱️ Save **~650 CI minutes/month**
500 - 💵 Save **~$5/month** (private repos)
501  
502 ### 💡 How to Fix
503 Run locally: `ghgen analyze --fix`
504  
505 =head2 Mode 2: Auto-Fix with Pull Request
506  
507 Automatically create PRs with fixes on a schedule:
508  
509 # .github/workflows/ghgen-autofix.yml
510 name: Weekly Workflow Optimization
511  
512 on:
513 schedule:
514 - cron: '0 9 * * 1' # Monday 9am UTC
515 workflow_dispatch: # Manual trigger
516  
517 permissions:
518 contents: write
519 pull-requests: write
520  
521 jobs:
522 optimize:
523 runs-on: ubuntu-latest
524 steps:
525 - uses: actions/checkout@v6
526 - uses: nigelhorne/App-GHGen@v1
527 with:
528 github-token: ${{ secrets.GITHUB_TOKEN }}
529 auto-fix: true
530 create-pr: true
531  
532 This creates a PR titled "🤖 Optimize GitHub Actions workflows" with all fixes applied.
533  
534 =head2 Mode 3: CI Quality Gate
535  
536 Fail builds if workflow issues are found:
537  
538 # .github/workflows/ghgen-check.yml
539 name: Workflow Quality Check
540  
541 on:
542 pull_request:
543 paths:
544 - '.github/workflows/**'
545  
546 permissions:
547 contents: read
548  
549 jobs:
550 check:
551 runs-on: ubuntu-latest
552 steps:
553 - uses: actions/checkout@v6
554 - uses: nigelhorne/App-GHGen@v1
555 id: check
556 - name: Fail if issues found
557 if: steps.check.outputs.issues-found > 0
558 run: |
559 echo "Found ${{ steps.check.outputs.issues-found }} issues"
560 exit 1
561  
562 =head1 SUPPORTED LANGUAGES
563  
564 =head2 Perl
565  
566 Comprehensive Perl testing with modern best practices.
567  
568 B<Features:>
569  
570 =over 4
571  
572 =item * Multi-OS testing (Ubuntu, macOS, Windows)
573  
574 =item * Multiple Perl versions (5.22 through 5.42, customizable)
575  
576 =item * Smart minimum-version detection from cpanfile, Makefile.PL, or dist.ini
577  
578 =item * CPAN module caching with local::lib
579  
580 =item * B<Syntax linting> with C<perl -c> across every matrix cell — catches compile-time errors on every tested OS and Perl version with no extra CPAN dependencies
581  
582 =item * Optional B<unused-variable check> via L<warnings::unused> (latest Perl + Ubuntu only)
583  
584 =item * Perl::Critic integration for code quality (latest Perl + Ubuntu only)
585  
586 =item * Devel::Cover for test coverage (latest Perl + Ubuntu only)
587  
588 =item * Proper environment variables (AUTOMATED_TESTING, NO_NETWORK_TESTING, NONINTERACTIVE_TESTING)
589  
590 =item * Cross-platform compatibility (C<shell: perl {0}> for linting; bash/cmd for tests)
591  
592 =back
593  
594 B<Example:>
595  
596 ghgen generate --type=perl --customize
597  
598 B<Generated workflow step order:>
599  
600 =over 4
601  
602 =item 1. C<actions/checkout@v6>
603  
604 =item 2. Setup Perl — C<shogo82148/actions-setup-perl@v1.44.2>
605  
606 =item 3. Cache CPAN modules — C<actions/cache@v5>
607  
608 =item 4. Install cpanm and C<local::lib>
609  
610 =item 5. Install project dependencies
611  
612 =item 6. B<Lint and syntax check> — all matrix cells (enabled by default)
613  
614 =item 7. Run tests
615  
616 =item 8. B<Check for unused variables> — latest Perl + Ubuntu only (opt-in)
617  
618 =item 9. Run Perl::Critic — latest Perl + Ubuntu only (enabled by default)
619  
620 =item 10. Test coverage — latest Perl + Ubuntu only (enabled by default)
621  
622 =item 11. Show cpanm build log on failure
623  
624 =back
625  
626 B<Workflow-level features:>
627  
628 =over 4
629  
630 =item * Security C<permissions: contents: read>
631  
632 =item * Concurrency group cancels superseded runs
633  
634 =item * C<fail-fast: false> so every matrix cell completes
635  
636 =back
637  
638 =head2 Node.js
639  
640 Modern Node.js workflows with npm/yarn/pnpm support.
641  
642 B<Features:>
643  
644 =over 4
645  
646 =item * Multiple Node.js versions (18.x, 20.x, 22.x)
647  
648 =item * Package manager selection (npm, yarn, pnpm)
649  
650 =item * Dependency caching (~/.npm, ~/.yarn, ~/.pnpm)
651  
652 =item * Optional linting (ESLint)
653  
654 =item * Optional build step
655  
656 =item * Lock file hash-based cache keys
657  
658 =back
659  
660 B<Customization options:>
661  
662 =over 4
663  
664 =item * Node.js versions to test
665  
666 =item * Package manager preference
667  
668 =item * Enable/disable linting
669  
670 =item * Enable/disable build step
671  
672 =back
673  
674 =head2 Python
675  
676 Python testing with virtual environment support.
677  
678 B<Features:>
679  
680 =over 4
681  
682 =item * Multiple Python versions (3.9, 3.10, 3.11, 3.12, 3.13)
683  
684 =item * pip caching (~/.cache/pip)
685  
686 =item * flake8 linting
687  
688 =item * pytest with coverage
689  
690 =item * Optional black formatter checking
691  
692 =item * requirements.txt hash-based cache
693  
694 =back
695  
696 =head2 Rust
697  
698 Rust workflows with cargo, clippy, and formatting.
699  
700 B<Features:>
701  
702 =over 4
703  
704 =item * Cargo registry and target caching
705  
706 =item * cargo fmt formatting check
707  
708 =item * Clippy linting with -D warnings
709  
710 =item * Comprehensive test suite
711  
712 =item * Optional release builds
713  
714 =item * Cargo.lock hash-based cache
715  
716 =back
717  
718 =head2 Go
719  
720 Go testing with modules and race detection.
721  
722 B<Features:>
723  
724 =over 4
725  
726 =item * Configurable Go version
727  
728 =item * Go modules caching (~/go/pkg/mod)
729  
730 =item * go vet for static analysis
731  
732 =item * Race detector (-race flag)
733  
734 =item * Test coverage with atomic mode
735  
736 =item * go.sum hash-based cache
737  
738 =back
739  
740 =head2 Ruby
741  
742 Ruby testing with Bundler integration.
743  
744 B<Features:>
745  
746 =over 4
747  
748 =item * Multiple Ruby versions (3.1, 3.2, 3.3)
749  
750 =item * Automatic Bundler caching (built into setup-ruby)
751  
752 =item * Gemfile.lock hash-based cache
753  
754 =item * Rake integration
755  
756 =back
757  
758 =head2 Docker
759  
760 Docker image building and publishing.
761  
762 B<Features:>
763  
764 =over 4
765  
766 =item * Docker Buildx for multi-platform builds
767  
768 =item * GitHub Container Registry (GHCR) support
769  
770 =item * Docker Hub support
771  
772 =item * Automatic tag extraction from git
773  
774 =item * Layer caching with GitHub Actions cache
775  
776 =item * Only pushes on non-PR events
777  
778 =back
779  
780 =head2 Static Sites
781  
782 Static site deployment to GitHub Pages.
783  
784 B<Features:>
785  
786 =over 4
787  
788 =item * GitHub Pages deployment
789  
790 =item * Configurable build command
791  
792 =item * Configurable build directory
793  
794 =item * Artifact upload
795  
796 =item * Proper Pages permissions
797  
798 =item * Separate build and deploy jobs
799  
800 =back
801  
802 =head1 CONFIGURATION DETECTION
803  
804 GHGen automatically detects configuration and adjusts workflows accordingly.
805  
806 =head2 Minimum Version Detection
807  
808 For Perl, minimum version is detected from:
809  
810 =over 4
811  
812 =item * cpanfile: C<requires 'perl', '5.036'>
813  
814 =item * Makefile.PL: C<MIN_PERL_VERSION =E<gt> '5.036'>
815  
816 =item * dist.ini: C<perl = 5.036>
817  
818 =back
819  
820 Only compatible Perl versions are tested (e.g., if min is 5.36, won't test 5.32 or 5.34).
821  
822 =head2 Dependency Files
823  
824 Caching is based on dependency files:
825  
826 =over 4
827  
828 =item * Perl: cpanfile, dist.ini, Makefile.PL, Build.PL
829  
830 =item * Node: package-lock.json, yarn.lock, pnpm-lock.yaml
831  
832 =item * Python: requirements.txt, Pipfile.lock
833  
834 =item * Rust: Cargo.lock
835  
836 =item * Go: go.sum
837  
838 =item * Ruby: Gemfile.lock
839  
840 =back
841  
842 =head1 BEST PRACTICES
843  
844 =head2 Workflow Generation
845  
846 =over 4
847  
848 =item * B<Use --auto for quick start> - Let GHGen detect your project
849  
850 =item * B<Use --customize for fine control> - Customize versions, OS, and features
851  
852 =item * B<Review before committing> - Always review generated workflows
853  
854 =item * B<Test locally first> - Use tools like C<act> to test locally
855  
856 =item * B<Start with defaults> - Customize only when needed
857  
858 =back
859  
860 =head2 Workflow Analysis
861  
862 =over 4
863  
864 =item * B<Run analyze regularly> - Weekly C<ghgen analyze> catches issues early
865  
866 =item * B<Use --estimate> - Monitor CI costs over time
867  
868 =item * B<Enable in CI> - Catch issues in PRs automatically
869  
870 =item * B<Review auto-fixes> - Always review changes before committing
871  
872 =item * B<Fix incrementally> - Don't fix everything at once if unsure
873  
874 =back
875  
876 =head2 Cost Optimization
877  
878 =over 4
879  
880 =item * B<Add caching> - Biggest time/cost savings
881  
882 =item * B<Add concurrency> - Cancel superseded runs
883  
884 =item * B<Filter triggers> - Only run on relevant changes
885  
886 =item * B<Optimize matrix> - Don't test unnecessary combinations
887  
888 =item * B<Run coverage once> - Only on one OS/version combination
889  
890 =back
891  
892 =head1 EXAMPLES
893  
894 =head2 Example 1: New Perl Module
895  
896 # In your new Perl module directory
897 cd My-Module/
898  
899 # Create cpanfile
900 echo "requires 'perl', '5.036';" > cpanfile
901  
902 # Auto-detect and generate
903 ghgen generate --auto
904  
905 # Review and commit
906 cat .github/workflows/perl-ci.yml
907 git add .github/workflows/perl-ci.yml cpanfile
908 git commit -m "Add CI workflow"
909 git push
910  
911 =head2 Example 2: Optimize Existing Project
912  
913 # Clone project
914 git clone https://github.com/user/project.git
915 cd project/
916  
917 # Analyze with cost estimation
918 ghgen analyze --estimate
919  
920 # Review suggestions, then fix
921 ghgen analyze --fix
922  
923 # Review changes
924 git diff .github/workflows/
925  
926 # Commit improvements
927 git add .github/workflows/
928 git commit -m "Optimize CI: add caching, update actions, add permissions"
929 git push
930  
931 =head2 Example 3: Multi-Language Project
932  
933 # Project with both Node.js and Docker
934 cd fullstack-app/
935  
936 # Generate Node.js workflow
937 ghgen generate --type=node --output=.github/workflows/frontend-ci.yml
938  
939 # Generate Docker workflow
940 ghgen generate --type=docker --output=.github/workflows/backend-build.yml
941  
942 # Analyze both
943 ghgen analyze
944  
945 =head2 Example 4: Custom Perl Testing Matrix
946  
947 # Interactive customization
948 ghgen generate --type=perl --customize
949  
950 # Choose:
951 # Perl versions: 5.36, 5.38, 5.40 (skip older)
952 # OS: Ubuntu, macOS (skip Windows if not needed)
953 # Perl::Critic: Yes
954 # Coverage: Yes
955 # Branches: main
956  
957 =head2 Example 5: CI Quality Gate
958  
959 Add workflow quality checks to your CI:
960  
961 # .github/workflows/ci-quality.yml
962 name: CI Quality Check
963  
964 on:
965 pull_request:
966 paths:
967 - '.github/workflows/**'
968  
969 jobs:
970 check:
971 runs-on: ubuntu-latest
972 steps:
973 - uses: actions/checkout@v6
974 - name: Install GHGen
975 run: cpanm --notest App::GHGen
976 - name: Check workflows
977 run: |
978 if ! ghgen analyze; then
979 echo "::error::Workflow quality issues found"
980 echo "Run 'ghgen analyze --fix' locally to fix"
981 exit 1
982 fi
983  
984 =head1 COMMAND REFERENCE
985  
986 =head2 generate
987  
988 ghgen generate [OPTIONS]
989  
990 Generate a new GitHub Actions workflow.
991  
992 B<Options:>
993  
994 =over 4
995  
996 =item C<--auto, -a>
997  
998 Auto-detect project type from repository contents.
999  
1000 =item C<--type=TYPE, -t TYPE>
1001  
1002 Specify project type: perl, node, python, rust, go, ruby, docker, static.
1003  
1004 =item C<--customize, -c>
1005  
1006 Enable interactive customization mode.
1007  
1008 =item C<--interactive, -i>
1009  
1010 Interactively select project type from menu.
1011  
1012 =item C<--output=FILE, -o FILE>
1013  
1014 Specify output file (default: .github/workflows/TYPE-ci.yml).
1015  
1016 =item C<--list, -l>
1017  
1018 List all available workflow types with descriptions.
1019  
1020 =back
1021  
1022 B<Examples:>
1023  
1024 ghgen generate --auto
1025 ghgen generate --type=perl --customize
1026 ghgen generate --interactive
1027 ghgen generate --type=node --output=custom.yml
1028  
1029 =head2 analyze
1030  
1031 ghgen analyze [OPTIONS]
1032  
1033 Analyze existing workflows for issues and optimization opportunities.
1034  
1035 B<Options:>
1036  
1037 =over 4
1038  
1039 =item C<--fix, -f>
1040  
1041 Automatically apply fixes to detected issues.
1042  
1043 =item C<--estimate, -e>
1044  
1045 Show cost estimates and potential savings.
1046  
1047 =back
1048  
1049 B<Examples:>
1050  
1051 ghgen analyze
1052 ghgen analyze --fix
1053 ghgen analyze --estimate
1054 ghgen analyze --fix --estimate
1055  
1056 =head1 TROUBLESHOOTING
1057  
1058 =head2 Installation Issues
1059  
1060 B<Problem:> C<cpanm> fails to install dependencies
1061  
1062 B<Solution:>
1063  
1064 # Install build tools first
1065 # On Debian/Ubuntu:
1066 sudo apt-get install build-essential
1067  
1068 # On macOS:
1069 xcode-select --install
1070  
1071 # Then retry
1072 cpanm App::GHGen
1073  
1074 =head2 Generation Issues
1075  
1076 B<Problem:> "No .github/workflows directory"
1077  
1078 B<Solution:>
1079  
1080 mkdir -p .github/workflows
1081 ghgen generate --auto
1082  
1083 B<Problem:> Auto-detect doesn't find my project type
1084  
1085 B<Solution:>
1086  
1087 # Specify type explicitly
1088 ghgen generate --type=perl
1089  
1090 # Or ensure indicator files exist
1091 touch cpanfile # for Perl
1092 touch package.json # for Node.js
1093  
1094 =head2 Analysis Issues
1095  
1096 B<Problem:> "Failed to parse YAML"
1097  
1098 B<Solution:>
1099  
1100 # Validate YAML syntax first
1101 yamllint .github/workflows/*.yml
1102  
1103 # Fix YAML errors, then retry
1104 ghgen analyze
1105  
1106 B<Problem:> Cost estimates seem wrong
1107  
1108 B<Solution:>
1109  
1110 Cost estimates are approximations based on:
1111  
1112 =over 4
1113  
1114 =item * Typical commit/PR frequency
1115  
1116 =item * Average workflow duration
1117  
1118 =item * Standard GitHub Actions pricing
1119  
1120 =back
1121  
1122 Actual costs depend on your specific usage patterns.
1123  
1124 =head2 Auto-Fix Issues
1125  
1126 B<Problem:> Auto-fix didn't fix everything
1127  
1128 B<Solution:>
1129  
1130 Some issues can't be auto-fixed:
1131  
1132 =over 4
1133  
1134 =item * Complex workflow logic
1135  
1136 =item * Custom actions
1137  
1138 =item * Project-specific configurations
1139  
1140 =back
1141  
1142 Review the remaining suggestions and apply manually.
1143  
1144 =head2 GitHub Action Issues
1145  
1146 B<Problem:> "Permission denied" errors
1147  
1148 B<Solution:>
1149  
1150 # Ensure correct permissions in workflow
1151 permissions:
1152 contents: write # For auto-fix
1153 pull-requests: write # For comments
1154  
1155 B<Problem:> Action not triggering
1156  
1157 B<Solution:>
1158  
1159 # For scheduled workflows, ensure:
1160 on:
1161 schedule:
1162 - cron: '0 9 * * 1'
1163 workflow_dispatch: # Allows manual trigger
1164  
1165 # Test with manual trigger first
1166  
1167 =head1 DEPENDENCIES
1168  
1169 =head2 Runtime Dependencies
1170  
1171 =over 4
1172  
1173 =item * Perl 5.36 or higher
1174  
1175 =item * L<YAML::XS> - Fast YAML parsing and generation
1176  
1177 =item * L<Path::Tiny> - File and directory operations
1178  
1179 =item * L<Term::ANSIColor> - Colored terminal output
1180  
1181 =item * L<Getopt::Long> - Command-line option parsing
1182  
1183 =back
1184  
1185 =head2 Test Dependencies
1186  
1187 =over 4
1188  
1189 =item * L<Test::More> - Testing framework
1190  
1191 =item * L<Test::Exception> - Exception testing
1192  
1193 =back
1194  
1195 =head2 Optional Dependencies
1196  
1197 =over 4
1198  
1199 =item * L<Pod::Markdown> - For generating README from POD
1200  
1201 =back
1202  
1203 =head1 SEE ALSO
1204  
1205 =over 4
1206  
1207 =item * L<GitHub Marketplace Releases|https://github.com/marketplace/actions/ghgen-workflow-analyzer>
1208  
1209 =item * L<Test Dashboard|https://nigelhorne.github.io/App-GHGen/coverage/>
1210  
1211 =item * L<App::Test::Generator>
1212  
1213 =back
1214  
1215 =head2 GitHub Actions Documentation
1216  
1217 =over 4
1218  
1219 =item * L<Workflow Syntax|https://docs.github.com/actions/reference/workflow-syntax-for-github-actions>
1220  
1221 =item * L<GitHub Actions Pricing|https://docs.github.com/billing/managing-billing-for-github-actions>
1222  
1223 =item * L<Security Hardening|https://docs.github.com/actions/security-guides/security-hardening-for-github-actions>
1224  
1225 =item * L<Caching Dependencies|https://docs.github.com/actions/using-workflows/caching-dependencies-to-speed-up-workflows>
1226  
1227 =back
1228  
1229 =head2 Related Tools
1230  
1231 =over 4
1232  
1233 =item * L<act|https://github.com/nektos/act> - Run GitHub Actions locally
1234  
1235 =item * L<actionlint|https://github.com/rhysd/actionlint> - Linter for GitHub Actions
1236  
1237 =item * L<yamllint|https://github.com/adrienverge/yamllint> - YAML linter
1238  
1239 =back
1240  
1241 =head1 REPOSITORY
1242  
1243 L<https://github.com/nigelhorne/App-GHGen>
1244  
1245 =head1 CONTRIBUTING
1246  
1247 Contributions are welcome! GHGen is open source and hosted on GitHub.
1248  
1249 =head2 Ways to Contribute
1250  
1251 =over 4
1252  
1253 =item * B<Report bugs> - L<GitHub Issues|https://github.com/nigelhorne/App-GHGen/issues>
1254  
1255 =item * B<Suggest features> - Open an issue with your idea
1256  
1257 =item * B<Add language support> - Contribute new workflow templates
1258  
1259 =item * B<Improve documentation> - Fix typos, add examples
1260  
1261 =item * B<Submit pull requests> - Code contributions
1262  
1263 =back
1264  
1265 =head2 Development Setup
1266  
1267 # Fork and clone
1268 git clone https://github.com/nigelhorne/ghgen.git
1269 cd ghgen
1270  
1271 # Install dependencies
1272 cpanm --installdeps .
1273  
1274 # Run tests
1275 prove -lr t/
1276  
1277 # Make changes
1278 # ... edit files ...
1279  
1280 # Test your changes
1281 perl -Ilib bin/ghgen generate --type=perl
1282 prove -lr t/
1283  
1284 # Commit and push
1285 git add .
1286 git commit -m "Description of changes"
1287 git push origin your-branch
1288  
1289 # Open pull request on GitHub
1290  
1291 =head2 Adding a New Language
1292  
1293 To add support for a new language:
1294  
1295 1. Create generator function in C<lib/App/GHGen/Generator.pm>
1296  
1297 2. Add detection logic in C<lib/App/GHGen/Detector.pm>
1298  
1299 3. Add customization in C<lib/App/GHGen/Interactive.pm>
1300  
1301 4. Add tests in C<t/>
1302  
1303 5. Update documentation
1304  
1305 =head1 SUPPORT
1306  
1307 This module is provided as-is without any warranty.
1308  
1309 Please report any bugs or feature requests to C<bug-app-ghgen at rt.cpan.org>,
1310 or through the web interface at
1311 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-GHGen>.
1312 I will be notified, and then you'll
1313 automatically be notified of progress on your bug as I make changes.
1314  
1315 You can find documentation for this module with the perldoc command.
1316  
1317 perldoc App::GHGen
1318  
1319 You can also look for information at:
1320  
1321 =head2 Getting Help
1322  
1323 =over 4
1324  
1325 =item * L<GitHub Issues|https://github.com/nigelhorne/App-GHGen/issues> - Bug reports and feature requests
1326  
1327 =item * L<GitHub Discussions|https://github.com/nigelhorne/App-GHGen/discussions> - Questions and community
1328  
1329 =item * Email: L<njh@nigelhorne.com|mailto:njh@nigelhorne.com>
1330  
1331 =back
1332  
1333 =head2 Commercial Support
1334  
1335 For commercial support, consulting, or custom development, contact the author.
1336  
1337 =head1 AUTHOR
1338  
1339 Nigel Horne E<lt>njh@nigelhorne.comE<gt>
1340  
1341 L<https://github.com/nigelhorne>
1342  
1343 =head1 CONTRIBUTORS
1344  
1345 Thanks to all contributors who have helped improve GHGen!
1346  
1347 See L<https://github.com/nigelhorne/App-GHGen/graphs/contributors>
1348  
1349 =head1 COPYRIGHT AND LICENSE
1350  
1351 Copyright 2025-2026 Nigel Horne.
1352  
1353 Usage is subject to the GPL2 licence terms.
1354 If you use it,
1355 please let me know.
1356  
1357 =cut
1358  
1359 1 1;
« lib/App/GHGen/Generator.pm ↑ Summary