[go-fan] Go Module Review: actionlint

[github-actions[bot]]

🐹 Go Fan Report: actionlint

Module Overview

actionlint (github.com/rhysd/actionlint) is a comprehensive static checker for GitHub Actions workflow files. It performs syntax validation, type checking of expressions, action input/output verification, reusable workflow analysis, embedded script validation (shellcheck & pyflakes), and security scanning for script injection and credential leaks.

• Repository: https://github.com/rhysd/actionlint
• Current Version: v1.7.10 (latest release: 2025-12-30)
• Stars: 3,544 ⭐
• Last Updated: 2026-02-02 (updated today!)

Current Usage in gh-aw

actionlint is a critical dependency in gh-aw, integrated as a compilation-time validator for GitHub Actions workflows. The integration is well-architected and production-ready.

Usage Statistics

• Files: 18 Go files directly reference actionlint
• Import Count: Docker-based execution (not Go library imports)
• Key APIs Used: JSON output format via Docker (-format '{{json .}}')

Architecture Highlights

1. Docker-Based Isolation

// pkg/cli/actionlint.go:219
docker run --rm -v "$(pwd)":/workdir -w /workdir rhysd/actionlint:latest

The project uses Docker exclusively rather than importing actionlint as a Go library. This provides:

• ✅ Version consistency across environments
• ✅ Zero Go module dependency conflicts
• ✅ Simplified deployment (no binary installation)

2. Intelligent Batch Processing

The codebase runs actionlint once for all workflow files, minimizing Docker startup overhead:

// pkg/cli/compile_batch_operations.go
func runBatchActionlint(lockFiles []string, ...) error

3. Rich Statistics & Reporting

Custom statistics tracking provides comprehensive insights:

• Total workflows checked
• Errors vs warnings breakdown
• Errors grouped by kind (runner-label, shellcheck, expression, etc.)
• Documentation URL generation for each error kind

4. Smart Timeout Management

Dynamic timeouts scale with workload: 1 minute per file, minimum 5 minutes.

5. Integration Points

• CLI: gh aw compile --actionlint
• Strict mode: gh aw compile --strict --actionlint (fails on errors)
• MCP server: Exposed as a compilation option
• CI/CD: Used in static analysis workflows

Research Findings

Recent Updates in v1.7.10

🎯 Major New Features

1. YAML Anchors and Aliases Support (#133)

jobs:
  test:
    services:
      nginx:
        credentials: &credentials
          username: ${{ secrets.user }}
          password: ${{ secrets.password }}
    steps:
      - run: ./download.sh
        env: *credentials  # ✅ Now validated!
      - run: ./check.sh
        env: *credential   # ❌ Typo detected!

This feature enables DRY (Don't Repeat Yourself) patterns in workflows while catching typos and undefined anchors.

2. Increased Workflow Dispatch Inputs (#598)

• Maximum inputs raised from 10 → 25
• Aligns with GitHub's December 2025 update

3. New Permission Support (#602)

• Added artifact-metadata permission validation

4. Enhanced Constant Detection

• Detects always-true/false conditions in if: statements
• Prevents logic bugs from constant expressions

⚡ Performance Improvements

• Refactored parser with Go 1.23 iterators
• Reduced memory allocations
• Faster validation times

🐛 Bug Fixes

• Fixed format() function parsing with extra {}
• Detects unsupported YAML merge key <<
• Improved error messages for snapshot.if context validation

🚫 Deprecations Handled

• Removed support for dropped macOS runner labels:
  • *-xl variants
  • macos-13, macos-13-large, macos-13-xlarge

Best Practices from Maintainers

1. Run Locally First: Catch errors before CI/CD
2. Review All Error Types: Address security warnings, not just syntax
3. Configure for Your Setup: Define custom self-hosted runner labels
4. Automate in CI: Include in validation pipelines
5. Use Expressions Carefully: Follow GitHub's script injection mitigation

Improvement Opportunities

🏃 Quick Wins

1. Add Configuration File Template

Issue: No actionlint.yaml exists in the repository.

Impact: Users with self-hosted runners see false positive "unknown runner label" errors.

Solution: Create .github/actionlint.yaml:

# Configuration for actionlint
# See: https://github.com/rhysd/actionlint/blob/main/docs/config.md

self-hosted-runner:
  labels:
    - ubuntu-custom
    - windows-custom
    - macos-custom

Benefit: Prevents false positives, improves user experience.

---

2. Document YAML Anchor Support

Issue: v1.7.10 added YAML anchor/alias support but gh-aw docs don't mention it.

Solution: Add examples to documentation showing anchor reuse:

# .github/workflows/example.md
steps:
  - name: Common env vars
    env: &common-env
      NODE_ENV: production
      LOG_LEVEL: info
  
  - name: Build
    env: *common-env  # Reuse env vars

Benefit: Reduces duplication, improves workflow maintainability.

---

3. Expose Configuration Options

Issue: Docker integration uses default actionlint settings only.

Solution: Add CLI flags:

gh aw compile --actionlint --actionlint-ignore "*/deprecated/*"
gh aw compile --actionlint --actionlint-config .github/actionlint.yaml

Benefit: Flexible linting for advanced users.

✨ Feature Opportunities

1. Hybrid Execution Mode (Docker + Native)

Current: 100% Docker-based execution (~1-2s startup overhead per run).

Opportunity: Offer programmatic API usage for Go users:

import "github.com/rhysd/actionlint"

func runActionlintNative(files []string) error {
    linter := actionlint.NewLinter(os.Stdout, actionlint.LinterOptions{
        Format: "{{json .}}",
    })
    // 10x faster than Docker!
}

Strategy: Try native first, fall back to Docker if unavailable.

Benefit:

• ⚡ 10x faster for developers with Go installed
• 🌐 Works offline without Docker daemon
• 🧪 Easier unit testing

---

2. Result Caching

Current: actionlint runs on all files every compilation.

Opportunity: Cache results by file hash:

type ActionlintCache struct {
    FileHash  string
    Results   []actionlintError
    Timestamp time.Time
}

// Only re-run if file changed
if cached := checkCache(lockFile); cached != nil {
    return cached
}

Benefit: Significantly faster re-compilation (2-5x for unchanged files).

---

3. Watch Mode

Current: Manual compilation required.

Opportunity: Add gh aw compile --watch:

// Use fsnotify (already a dependency!)
watcher.Add(".github/workflows")
for event := range watcher.Events {
    if strings.HasSuffix(event.Name, ".md") {
        compile()
        runActionlint()
    }
}

Benefit: Instant feedback during workflow development.

---

4. Pre-commit Hook

Current: actionlint runs during gh aw compile.

Opportunity: Add pre-commit integration:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rhysd/actionlint
    rev: v1.7.10
    hooks:
      - id: actionlint

Benefit: Catch errors before committing.

📐 Best Practice Alignment

1. Pin Docker Image Version

Current: Uses rhysd/actionlint:latest

Best Practice: Pin to specific version for reproducibility.

Recommendation:

const DefaultActionlintImage = "rhysd/actionlint:v1.7.10"

// Allow override via env var
actionlintImage := os.Getenv("ACTIONLINT_IMAGE")
if actionlintImage == "" {
    actionlintImage = DefaultActionlintImage
}

Benefit: Reproducible builds, controlled upgrades.

---

2. Distinguish Exit Codes

Current: Generic exit code 1 handling.

Best Practice: actionlint uses specific codes:

• 0: No errors
• 1: Linting errors found
• 2: Fatal error (file not found, etc.)

Recommendation:

if exitCode == 2 {
    return fmt.Errorf("actionlint fatal error: %w", err)
} else if exitCode == 1 {
    // Linting errors - handle normally
}

Benefit: Better error messages and debugging.

---

3. Extract Docker Command Building

Current: Inline Docker command construction.

Improvement: Extract to testable function:

func buildActionlintDockerCommand(gitRoot string, files []string) *exec.Cmd {
    args := []string{"run", "--rm", 
        "-v", fmt.Sprintf("%s:/workdir", gitRoot),
        "rhysd/actionlint:latest", "-format", "{{json .}}"}
    args = append(args, files...)
    return exec.Command("docker", args...)
}

Benefit: Easier testing and maintainability.

🔧 General Improvements

1. Comprehensive Documentation Links

Status: Already implemented excellently!

The getActionlintDocsURL() function intelligently maps error kinds to documentation anchors. This is a best-in-class implementation.

Suggestion: Add unit tests to prevent doc link rot as actionlint evolves.

---

2. Statistics Display

Status: Well-implemented with color-coded output and breakdown by error kind.

Minor Enhancement: Add trend tracking across compilations:

// Show improvement over last run
fmt.Fprintf(os.Stderr, "Previous: %d errors → Current: %d errors (%s)\n", 
    prev, curr, getDelta(prev, curr))

Recommendations

Priority 1: Quick Wins (1-2 hours)

1. ✅ Add actionlint.yaml configuration template
2. ✅ Document YAML anchor support in examples
3. ✅ Expose --actionlint-ignore and --actionlint-config flags

Priority 2: Performance (4-8 hours)

1. ⚡ Implement result caching based on file hashes
2. ⚡ Add hybrid Docker/native execution mode

Priority 3: Developer Experience (2-4 hours)

1. 📝 Add pre-commit hook documentation
2. 📝 Add watch mode with auto-recompilation
3. 📝 Pin Docker image to versioned tag by default

Priority 4: Code Quality (2-3 hours)

1. 🧪 Extract Docker command building to testable function
2. 🧪 Add unit tests for error kind documentation mapping
3. 🧪 Distinguish between linting errors (exit 1) and fatal errors (exit 2)

Next Steps

Immediate Actions

1. Create actionlint.yaml template in .github/ with self-hosted runner examples
2. Update documentation to mention YAML anchor support in v1.7.10
3. Add CLI flags for --actionlint-ignore and --actionlint-config

Medium-term Enhancements

1. Prototype result caching to measure performance gains
2. Evaluate hybrid execution (native + Docker) for developer experience improvements
3. Add pre-commit hook example to documentation

Long-term Considerations

1. Monitor actionlint releases for new features (follow repo updates)
2. Consider contributing back to actionlint project with gh-aw learnings
3. Benchmark Docker vs native performance in CI environments

---

Module Summary: actionlint is exceptionally well-integrated in gh-aw with production-ready Docker orchestration, intelligent batch processing, and excellent error reporting. The main opportunities lie in adding configuration flexibility, performance optimizations through caching, and leveraging new v1.7.10 features like YAML anchors.

Overall Assessment: ✅ Excellent integration with room for incremental improvements

---

Generated by Go Fan 🐹
Review Date: 2026-02-02
Module Summary: scratchpad/mods/rhysd-actionlint.md
Next Module: Following round-robin, the next review will prioritize recently updated dependencies not reviewed in the last 7 days.

AI generated by Go Fan

• expires on Feb 9, 2026, 7:28 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-09T07:28:57.989Z.

Closed by Workflow