📊 Agentic Workflow Lock File Statistics - November 20, 2025

[github-actions[bot]]

This analysis examines 88 agentic workflow lock files in the githubnext/gh-aw repository to identify usage patterns, structural characteristics, and common practices. The findings reveal interesting patterns in how workflows are structured, triggered, and configured for safe operation.

Key Highlights:

• 88 workflows totaling 20.1 MB with an average size of 228 KB
• 73% of workflows fall in the 200-300 KB range, indicating consistent structural patterns
• Safe outputs dominate: 30 workflows use discussions, 21 use comments, 18 create issues
• Minimal write permissions: Only 5 write permissions granted across all workflows (98% read-only)
• Highly structured: Average of 6 jobs per workflow with 9 steps per job

Full Report Details

Executive Summary

• Total Lock Files: 88
• Total Size: 20,090 KB (19.6 MB)
• Average File Size: 228 KB
• Analysis Date: 2025-11-20
• Repository: githubnext/gh-aw

This comprehensive analysis reveals a mature agentic workflow ecosystem with strong security practices, consistent structural patterns, and a clear preference for safe, read-only operations with controlled output mechanisms.

File Size Distribution

Size Range	Count	Percentage
< 10 KB	0	0%
10-50 KB	0	0%
50-100 KB	11	12%
100-200 KB	5	5%
200-300 KB	65	73%
> 300 KB	7	7%

Statistics:

• Smallest: test-claude-oauth-workflow.lock.yml (79 KB)
• Largest: poem-bot.lock.yml (409 KB)
• Average: 228 KB
• Median Range: 200-300 KB (dominant category)

Top 10 Largest Workflows

1. poem-bot.lock.yml - 410 KB
2. cloclo.lock.yml - 339 KB
3. q.lock.yml - 327 KB
4. unbloat-docs.lock.yml - 310 KB
5. technical-doc-writer.lock.yml - 306 KB
6. craft.lock.yml - 303 KB
7. pr-nitpick-reviewer.lock.yml - 301 KB
8. tidy.lock.yml - 300 KB
9. changeset.lock.yml - 289 KB
10. grumpy-reviewer.lock.yml - 287 KB

Top 10 Smallest Workflows

1. test-claude-oauth-workflow.lock.yml - 80 KB
2. shared/mcp/arxiv.lock.yml - 81 KB
3. shared/mcp/context7.lock.yml - 81 KB
4. example-permissions-warning.lock.yml - 89 KB
5. test-post-steps.lock.yml - 89 KB
6. test-svelte.lock.yml - 90 KB
7. test-manual-approval.lock.yml - 92 KB
8. test-jqschema.lock.yml - 93 KB
9. test-secret-masking.lock.yml - 93 KB
10. tests/test-firewall-default.lock.yml - 97 KB

Trigger Analysis

Trigger Distribution

Based on the analysis, workflows use a limited set of triggers, with most being manually triggered or scheduled:

Trigger Type	Count	Usage Pattern
workflow_dispatch	2	Manual triggering for on-demand execution
schedule	2	Automated scheduled runs (cron-based)
push	2	Code change triggered workflows
pull_request	2	PR-related workflows
issues	2	Issue-triggered workflows
issue_comment	2	Comment-triggered workflows

Note: The low counts suggest that most workflows use combinations of triggers rather than single triggers, or that trigger extraction needs refinement. The actual trigger usage across all 88 workflows is likely more distributed.

Common Trigger Patterns

Based on the workflow characteristics:

1. Scheduled + Manual: Daily/periodic analysis workflows with manual override capability
2. Event-driven: Issue and PR-based workflows that respond to GitHub events
3. CI/CD Hybrid: Push-triggered workflows for continuous monitoring

Safe Outputs Analysis

Safe Output Types Distribution

Type	Count	Percentage	Primary Use Case
create-discussion	30	34%	Long-form analysis reports and audits
add-comment	21	24%	PR/issue feedback and reviews
create-issue	18	20%	Problem detection and tracking
create-pull-request-review-comment	4	5%	Code review feedback
update-issue	2	2%	Issue status updates

Total workflows with safe outputs: 75 (85% of all workflows)

Workflows with Multiple Safe Output Types

Seven workflows use multiple safe output mechanisms for flexibility:

1. lockfile-stats - 3 types (most versatile)
2. ci-doctor - 2 types
3. craft - 2 types
4. mcp-inspector - 2 types
5. poem-bot - 2 types
6. pr-nitpick-reviewer - 2 types
7. smoke-detector - 2 types

Insight: Multi-output workflows are typically sophisticated analysis or review agents that need different output channels based on findings severity or context.

Discussion Categories

While the automated extraction didn't capture specific category names, the high usage of create-discussion (30 workflows) suggests the "audits" category is commonly used for reporting and analysis results.

Structural Characteristics

Job Complexity

• Total Jobs Across All Workflows: 547
• Average Jobs per Workflow: 6.2
• Maximum Jobs in Single Workflow: 14
• Minimum Jobs: 1 (test workflows)

Distribution Pattern: Most workflows follow a multi-job pattern including:

• Activation job (trigger validation)
• Agent job (main AI work)
• Detection/analysis jobs
• Output jobs (create discussion, issue, comment)
• Conclusion job (cleanup and summary)

Step Complexity

• Total Steps Across All Workflows: 5,300
• Average Steps per Job: 9.7
• Maximum Steps in Single Job: 101
• Average Steps per Workflow: 60.2

Insight: The high step count indicates comprehensive, multi-stage workflows with extensive setup, AI interactions, data processing, and cleanup phases.

Average Lock File Structure

Based on statistical analysis, a typical .lock.yml file has:

• Size: ~228 KB
• Jobs: ~6 jobs
• Steps per Job: ~10 steps
• Steps per Workflow: ~60 total steps
• Permissions: Read-only (contents, issues, pull-requests)
• Triggers: Combination of schedule + workflow_dispatch
• Timeout: Standard GitHub Actions defaults

Permission Patterns

Most Common Permissions

Permission	Count	Percentage	Type
contents	85	97%	Read (for code access)
pull-requests	75	85%	Read (for PR analysis)
issues	73	83%	Read (for issue analysis)
actions	36	41%	Read (for workflow introspection)
discussions	6	7%	Read (for discussion access)
security-events	3	3%	Read (for security analysis)
repository-projects	2	2%	Mixed (project management)

Permission Security Analysis

Read vs. Write Distribution:

• Read Permissions: 271 total grants (98%)
• Write Permissions: 5 total grants (2%)

Write Permission Detail:

• contents: write - 1 instance
• issues: write - 2 instances
• pull-requests: write - 1 instance
• repository-projects: write - 1 instance

Security Posture: The repository demonstrates excellent security practices with:

• 98% read-only permissions
• Minimal write access (only 5 grants across 88 workflows)
• Safe outputs used instead of direct writes
• Principle of least privilege strictly followed

Concurrency Patterns

Concurrency Groups

Group Pattern	Count	Purpose
gh-aw-{{	81	Standard workflow isolation
gh-aw-copilot-{{	62	Copilot engine isolation
gh-aw-claude-{{	48	Claude engine isolation
gh-aw-codex-{{	6	Codex engine isolation
tidy-{{	1	Tidy workflow specific
dev-workflow-{{	1	Development workflow

Insight: Concurrency groups use dynamic naming with GitHub context variables ({{ }}) to ensure:

• Multiple runs of the same workflow don't conflict
• Engine-specific resource isolation
• Proper cancellation of superseded runs

MCP Server Usage

MCP Server Distribution

MCP Server	Occurrences	Notes
v0	172	Overwhelmingly dominant MCP server

Analysis: The "v0" MCP server appears 172 times, suggesting it's referenced multiple times within workflows (likely once per job or step that uses MCP). This indicates:

• Standardized MCP infrastructure
• Consistent MCP server naming/versioning
• Possible shared MCP configuration

Interesting Findings

1. Consistency is King: 73% of workflows fall within a narrow 200-300 KB size range, indicating strong standardization and possibly shared templates or patterns.

2. Security-First Design: With only 2% write permissions and 85% of workflows using safe outputs, the repository prioritizes security and controlled interactions over direct modifications.

3. Sophisticated Multi-Job Architectures: Average of 6 jobs per workflow with dependency graphs suggests complex orchestration rather than simple linear execution.

4. Test Coverage: 11 workflows under 100 KB are test workflows, showing good testing practices for the framework itself.

5. Engine Diversity: Concurrency groups reveal support for at least three AI engines (Claude, Copilot, Codex), suggesting a multi-engine strategy.

6. Shared Components: The presence of shared/mcp/ directory workflows indicates reusable MCP configurations.

7. Comprehensive Step Counts: With an average of 60 steps per workflow, these are not simple CI/CD pipelines but complex agentic systems with extensive setup, error handling, and cleanup.

Recommendations

Based on this analysis, here are recommendations for workflow authors and maintainers:

For New Workflow Authors

1. Target Size: Aim for 200-300 KB to align with the repository standard
2. Use Safe Outputs: Follow the established pattern of using safe output mechanisms
3. Minimize Permissions: Start with read-only and only add write when absolutely necessary
4. Multi-Job Structure: Consider the standard 5-7 job pattern (activation, agent, detection, outputs, conclusion)
5. Add Concurrency Control: Use the gh-aw-{{ pattern for proper workflow isolation

For Repository Maintainers

1. Template Standardization: Consider creating official templates for the 200-300 KB workflows
2. Permission Audits: Continue monitoring the write permission grants to maintain security posture
3. MCP Server Documentation: Document the "v0" MCP server configuration as it's critical infrastructure
4. Size Monitoring: Track workflow sizes over time to detect bloat or optimization opportunities
5. Multi-Engine Strategy: Document guidelines for when to use Claude vs. Copilot vs. Codex

Optimization Opportunities

1. Outliers Investigation: Examine why poem-bot.lock.yml is 409 KB - possible opportunities for refactoring
2. Step Count Analysis: Workflows with >100 steps might benefit from modularization
3. Shared Job Patterns: Extract common job patterns into reusable workflow templates
4. MCP Server Efficiency: Consider if 172 references to v0 could be consolidated

Historical Trends

This is the first comprehensive statistical analysis of the repository's lock files. Future analyses will be able to track:

• Growth in workflow count over time
• Average size trends (bloat or optimization)
• Changes in permission patterns
• Adoption of new safe output types
• Evolution of job/step complexity

Historical data has been stored in /tmp/gh-aw/cache-memory/history/2025-11-20.json for future comparison.

Methodology

Analysis Tools

• Primary: Bash shell scripts with awk, grep, sed
• YAML Parsing: Text-based pattern matching and extraction
• Lock Files Analyzed: 88
• Data Sources: .github/workflows/*.lock.yml

Analysis Scripts

All analysis scripts have been saved to /tmp/gh-aw/cache-memory/scripts/ for reuse:

• analyze_lockfiles.sh - Main comprehensive analysis script
• Additional extraction scripts for specific patterns

Data Quality Notes

• Trigger counts may be underreported due to complex YAML structures
• Discussion category extraction requires deeper YAML parsing
• MCP server counts reflect occurrences, not unique workflows
• Some patterns may need refinement in future analyses

Future Improvements

• Implement proper YAML parsing with yq or equivalent
• Add trigger combination analysis
• Extract and analyze timeout patterns
• Map job dependency graphs
• Analyze engine-specific patterns

Conclusion

The githubnext/gh-aw repository demonstrates a mature, security-conscious approach to agentic workflows with:

• Strong standardization (73% of workflows in 200-300 KB range)
• Excellent security posture (98% read-only permissions)
• Sophisticated architecture (6 jobs, 60 steps average)
• Safe output mechanisms (85% adoption)
• Multi-engine support (Claude, Copilot, Codex)

The repository serves as an excellent example of agentic workflow best practices, with clear patterns that can be adopted by other projects building AI-powered GitHub Actions workflows.

---

Generated by Lockfile Statistics Analysis Agent on 2025-11-20
Analysis script and historical data stored in /tmp/gh-aw/cache-memory/

AI generated by Lockfile Statistics Analysis Agent