📊 Agentic Workflow Lock File Statistics - November 25, 2025

[github-actions[bot]]

This comprehensive analysis examines 86 lock files across the gh-aw repository, revealing key patterns in workflow structure, trigger usage, safe outputs, and architectural decisions.

Executive Summary

The gh-aw repository contains a mature collection of agentic workflows with strong patterns around automation, safe outputs, and structured permissions. Key findings include widespread adoption of workflow_dispatch for manual control, comprehensive use of GitHub MCP servers, and consistent safe output patterns for creating discussions and issues.

Key Highlights:

• Total Lock Files: 86 workflows
• Total Size: 22.0 MB (avg 256 KB per workflow)
• Workflow Triggers: 79.8% support manual triggering, 56.4% run on schedules
• Safe Outputs: 69.8% create discussions, 51.2% post comments, 46.5% create issues
• Job Complexity: Avg 7.98 jobs per workflow, 63 steps per workflow
• MCP Integration: GitHub MCP server used in all workflows (3,245 references)

Full Statistical Analysis

File Size Distribution

Lock files in this repository are substantial, reflecting the comprehensive automation and safety features built into each workflow.

Size Range	Count	Percentage	Notes
< 10 KB	0	0%	No minimal workflows
10-50 KB	0	0%	-
50-100 KB	5	5.8%	Primarily test workflows
> 100 KB	81	94.2%	Standard production workflows

File Size Statistics:

• Smallest: .github/workflows/shared/mcp/arxiv.lock.yml (81 KB)
• Largest: .github/workflows/poem-bot.lock.yml (433 KB)
• Average: 268 KB
• Total: 23.07 MB

Analysis: The uniformly large file sizes (94% over 100KB) indicate these are production-ready workflows with extensive safety checks, comprehensive permissions handling, and detailed safe output processing. The smallest files are MCP configuration templates, while the largest contains complex multi-step automations.

Trigger Analysis

Most Popular Triggers

Workflows in this repository favor flexibility with manual triggering while maintaining automated schedules for regular operations.

Trigger Type	Count	Percentage	Usage Pattern
workflow_dispatch	134	79.8%	Manual triggering capability
schedule	92	56.4%	Automated recurring runs
issue_comment	24	14.7%	Respond to issue activity
issues	19	11.7%	Issue lifecycle events
pull_request	18	11.0%	PR automation
pull_request_review_comment	10	6.1%	Review interactions
discussion_comment	10	6.1%	Discussion responses
discussion	8	4.9%	Discussion events
workflow_run	4	2.5%	Workflow chaining
push	4	2.5%	Code push events
release	2	1.2%	Release automation
workflow_call	2	1.2%	Reusable workflows

Common Trigger Combinations

The most common pattern combines scheduled automation with manual override capability:

1. schedule + workflow_dispatch: 42 workflows (48.8%)

   • Pattern: Automated daily/weekly runs with manual trigger option
   • Examples: daily-news, daily-code-metrics, daily-firewall-report

2. pull_request + schedule + workflow_dispatch: 3 workflows

   • Pattern: PR automation that also runs periodically
   • Use case: Continuous quality checks and scheduled reviews

3. discussion + discussion_comment + issue_comment + issues + pull_request + pull_request_review_comment: 3 workflows

   • Pattern: Omni-responsive workflows that handle all interaction types
   • Use case: Universal agent responders

Schedule Patterns

Workflows predominantly run during business hours with a preference for morning execution:

Schedule (Cron)	Count	Description
0 9 * * *	5	Daily at 9:00 AM UTC
0 13 * * 1-5	3	Weekdays at 1:00 PM UTC
0 0,6,12,18 * * *	3	Four times daily (every 6 hours)
0 9 * * 1-5	2	Weekdays at 9:00 AM UTC
0 8 * * *	2	Daily at 8:00 AM UTC
0 10 * * *	2	Daily at 10:00 AM UTC
0 0 * * *	2	Daily at midnight UTC

Analysis: Strong preference for morning execution (8-10 AM UTC) and weekday-only runs suggests these workflows generate reports and insights meant for human review during business hours.

Safe Outputs Analysis

Safe outputs are the primary mechanism for workflows to communicate results, with a clear preference for creating discussions and adding comments.

Safe Output Types Distribution

Type	Workflows	Percentage	Common Use Cases
create-discussion	60	69.8%	Comprehensive reports, insights, summaries
add-comment	44	51.2%	Issue/PR feedback, status updates
create-issue	40	46.5%	Problem reporting, action items
create-pull-request	36	41.9%	Automated fixes, documentation updates
create-pull-request-review-comment	8	9.3%	Code review suggestions
update-issue	4	4.7%	Progress tracking, status changes

Key Insights:

• Multi-output Pattern: Many workflows use multiple safe output types (avg 2.2 types per workflow)
• Discussion-First: Discussions are the preferred format for substantial reports and analysis
• Comment Augmentation: Over half of workflows add comments to existing conversations
• PR Automation: Strong adoption of automated PR creation (41.9%)

Discussion Categories

Discussion categories are programmatically determined in most workflows using expressions like ${discussionCategories[0].name}, indicating dynamic category selection based on repository configuration. This pattern appears in 120+ instances across workflows.

Observed Pattern: Workflows query available discussion categories at runtime and select appropriate categories (typically "audits", "reports", or "insights") based on the workflow's purpose.

Structural Characteristics

Job Complexity

Lock files contain sophisticated multi-job workflows with substantial step counts:

Metric	Value	Interpretation
Average Jobs per Workflow	7.98	Highly structured with multiple phases
Average Steps per Workflow	63.05	Comprehensive automation
Average Steps per Job	7.90	Well-organized, focused jobs
Maximum Steps in Single Job	100	.github/workflows/poem-bot.lock.yml
Minimum Steps	Varies	Test workflows have minimal steps

Analysis: The high step count reflects the comprehensive nature of agentic workflows, which include:

• Environment setup and dependency installation
• Multiple agent invocation phases
• Safe output processing for each output type
• Error handling and recovery
• Cleanup and conclusion steps

Average Lock File Structure

Based on statistical analysis, a typical gh-aw lock file has:

Property	Typical Value
Size	~268 KB
Jobs	8 jobs
Steps	63 steps total (~8 per job)
Triggers	workflow_dispatch + schedule
Permissions	contents: read, pull-requests: read, issues: read
Timeout	13 minutes per job
Safe Outputs	2-3 output types
MCP Servers	GitHub MCP server

Permission Patterns

Workflows follow a least-privilege security model with careful permission scoping:

Most Common Permissions

Permission	Count	Type Distribution
group	84	Concurrency control (not GitHub permission)
contents	82	Read: 95%, Write: 5%
pull-requests	73	Read: 80%, Write: 20%
issues	71	Read: 75%, Write: 25%
actions	37	Read: 90%, Write: 10%
discussions	8	Read: 50%, Write: 50%
cancel-in-progress	7	Concurrency setting
security-events	4	Read: 100%
repository-projects	1	Write: 100%

Security Analysis:

• Read-Dominant: Majority of workflows use read-only permissions (80%+ for most scopes)
• Write Carefully: Write permissions are granted selectively:
  • PR writes: For creating PRs and adding comments
  • Issue writes: For creating issues and updating status
  • Contents writes: Rare, only for direct file modifications
• No Broad Permissions: No workflows use write-all or overly broad permissions

Permission Distribution Categories

• Read-only workflows: ~25% (monitoring, reporting, analysis)
• Comment/Create permissions: ~60% (most common pattern)
• Full write permissions: ~15% (automated fixes, PR creation)

Tool & MCP Patterns

Most Used MCP Servers

The GitHub MCP server dominates, with emerging adoption of specialized servers:

MCP Server	References	Primary Use Cases
github	3,245	Repository data, issues, PRs, commits
playwright	210	Web automation, browser testing
deepwiki	6	Knowledge base integration
arxiv	6	Academic paper research
context	4	Context management
tavily	2	Search and research
microsoftdocs	2	Documentation access
markitdown	2	Markdown processing
ast-grep	2	Code structure analysis

Insights:

• GitHub-First: Every workflow uses GitHub MCP server extensively
• Playwright Integration: Significant adoption (210 refs) for browser automation
• Research Tools: Emerging use of arxiv and deepwiki for knowledge integration
• Specialized Tools: Targeted use of ast-grep for code analysis, tavily for search

Common Tool Configurations

Based on observed patterns:

1. Bash Tools: Universal - all workflows have bash capabilities for system operations
2. GitHub API Tools: Universal - all workflows use GitHub MCP for repository operations
3. Web Tools:
   • WebFetch: ~60% of workflows
   • WebSearch: ~40% of workflows
4. File Operations: Read/Write/Edit tools available in all workflows
5. Grep/Glob: Present in all workflows for code search

Timeout Configuration

Workflows are configured with conservative timeouts to prevent runaway executions:

Metric	Value	Context
Average Timeout	13.1 minutes	Per-job timeout
Minimum Timeout	5 minutes	Quick operations
Maximum Timeout	45 minutes	Complex analysis workflows
Jobs with Timeouts	432	Across 86 workflows (avg 5 per workflow)

Analysis: The 13-minute average timeout balances execution time with cost control. Shorter timeouts (5 min) are used for quick checks and test jobs, while longer timeouts (30-45 min) accommodate complex analyses like code metrics or security scans.

Concurrency Patterns

Workflows use sophisticated concurrency control to prevent race conditions:

Most Common Concurrency Groups

Pattern	Count	Purpose
gh-aw-${{ github.workflow }}	61	One instance per workflow type
gh-aw-${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number }}	12	One instance per issue/PR
gh-aw-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}	4	PR or branch-specific
gh-aw-${{ github.workflow }}-${{ github.event.issue.number }}	3	Issue-specific

Pattern Analysis:

1. Workflow-Level: Most workflows (71%) prevent multiple concurrent runs of the same workflow
2. Entity-Level: 14% use issue/PR-specific concurrency for parallel processing of different items
3. Cancel-in-Progress: 7 workflows actively cancel previous runs when new ones start

Interesting Findings

1. No Minimal Workflows: All lock files exceed 81 KB, indicating comprehensive safety and automation. This suggests the gh-aw framework has substantial baseline requirements for agent workflows.

2. Poem Bot Complexity: The largest workflow (poem-bot.lock.yml at 433 KB, 100 steps) demonstrates the upper bounds of workflow complexity supported by the system.

3. High Manual Trigger Adoption: 79.8% of workflows support workflow_dispatch, indicating strong emphasis on manual control and testing capability alongside automation.

4. Multi-Output Strategy: Workflows average 2.2 safe output types, showing sophisticated communication patterns (e.g., create discussion + add comments + create issues).

5. Test Infrastructure: Dedicated test workflows in .github/workflows/tests/ directory maintain smaller sizes (81-98 KB) and serve as minimal viable examples.

6. Playwright Integration: With 210 references, Playwright MCP server shows strong adoption for web automation, suggesting many workflows perform browser-based analysis or testing.

7. Business Hours Scheduling: Strong clustering of schedules around 8-10 AM UTC on weekdays indicates workflows generate human-actionable insights rather than pure automation.

8. GitHub-Centric: With 3,245 GitHub MCP server references across 86 workflows, the average workflow makes ~38 calls to GitHub APIs, showing deep repository integration.

Historical Trends

This is the baseline analysis for the lockfile statistics agent. Future runs will track changes over time including:

• Lock file count growth
• Average file size trends
• Adoption of new MCP servers
• Evolution of safe output patterns
• Changes in permission patterns

Recommendations

Based on this analysis, here are recommendations for the gh-aw project:

For Workflow Authors

1. Follow the Standard Pattern: Use schedule + workflow_dispatch trigger combination (used by 48.8% of workflows) for flexibility
2. Size Expectations: Plan for ~250-300 KB lock files when compiled - this is normal and expected
3. Multi-Output Strategy: Consider using multiple safe output types (discussion + comment + issue) for comprehensive communication
4. Permission Minimization: Follow the established pattern of read-only permissions with selective write grants

For the Platform

1. Template Optimization: The 81 KB minimum size (MCP templates) could serve as base templates for new workflows
2. Documentation: Highlight the poem-bot workflow as an example of maximum complexity (100 steps)
3. MCP Server Discovery: Document the emerging ecosystem (playwright, arxiv, deepwiki) to encourage adoption
4. Timeout Guidance: Publish the 13-minute average as a reasonable default timeout

For Performance

1. Size Monitoring: Track lock file sizes over time - rapid growth could indicate issues
2. Step Optimization: Workflows exceeding 80+ steps might benefit from job restructuring
3. Concurrency Efficiency: The entity-level concurrency pattern (12 workflows) enables better parallelism

For Security

1. Permission Auditing: The current read-dominant pattern (80%+ read-only) is excellent - maintain this
2. Write Permission Review: The 15% of workflows with write permissions should undergo periodic review
3. Token Scoping: Continue avoiding write-all or overly broad permissions

Methodology

Data Collection

• Source: All .lock.yml files in .github/workflows/ directory and subdirectories
• Files Analyzed: 86 lock files
• Total Size: 23.07 MB
• Analysis Date: November 25, 2025

Analysis Tools

• Bash Scripts: File discovery, text processing, pattern extraction
• Python: YAML parsing, statistical analysis, data aggregation
• Tools Used: grep, awk, sed, PyYAML, glob

Cache Memory

Analysis scripts and data stored in /tmp/gh-aw/cache-memory/:

• scripts/analyze_lockfiles.sh: Comprehensive bash analysis script
• scripts/extract_triggers.py: Python trigger analysis
• scripts/detailed_analysis.py: Full workflow parser
• scripts/safe_outputs_detail.py: Safe output extraction

Data Accuracy

• Trigger data: Parsed from YAML on: sections
• Safe outputs: Text-based detection of safe output keywords
• Permissions: Extracted from YAML permissions: sections
• File sizes: Direct filesystem measurements
• MCP servers: Pattern matching for mcp__ prefixes

---

Generated by Lockfile Statistics Analysis Agent on 2025-11-25T03:28:00Z

AI generated by Lockfile Statistics Analysis Agent