[go-fan] Go Module Review: actionlint (github.com/rhysd/actionlint)

[github-actions[bot]]

🐹 Go Fan Report: github.com/rhysd/actionlint

Selected via round-robin (most recently pushed of unreviewed direct deps: pushed 2026-03-23). Run §23529573616.

---

Module Overview

actionlint is a static checker for GitHub Actions workflow files. It validates YAML syntax, type-checks $\{\{ }} expressions, validates action inputs/outputs against a curated dataset of popular actions, checks reusable workflow calls, and integrates with shellcheck/pyflakes for shell and Python script linting. It also performs security checks for script injection and hard-coded credentials.

Current version in go.mod: v1.7.11 (released 2026-02-14).

---

Current Usage in gh-aw

Metric	Value
Files touching actionlint	24
Direct Go API calls	0 (none in production code)
Integration method	Docker subprocess
Docker image used	rhysd/actionlint:latest

The module is used in two distinct ways:

1. Version pinning only (tools.go)

//go:build tools
import _ "github.com/rhysd/actionlint/cmd/actionlint"
```
This blank import ensures `go.mod` tracks `v1.7.11` but the Go API is never called directly in production code.

**2. Docker subprocess (`pkg/cli/actionlint.go`)**
All actual linting runs through Docker:
```
docker run --rm -v "<gitroot>:/workdir" -w /workdir rhysd/actionlint:latest -format '\{\{json .}}' <files...>

JSON output is unmarshalled into an actionlintError struct and reformatted for display. Exit codes are handled: 0 = clean, 1 = lint errors found, other = tooling failure.

Key implementation features:

• Batch processing: all lock files passed to a single Docker invocation
• Dynamic timeout: max(5, len(files)) minutes
• Aggregate stats: ActionlintStats tracks totals + per-kind breakdown
• Custom docs URL mapper: getActionlintDocsURL(kind) maps error kind → docs anchor
• Strict mode: errors become compilation failures; non-strict mode logs but continues

---

Research Findings

Recent Updates (v1.7.9–v1.7.11)

v1.7.11 (2026-02-14) — current pinned version

• case() expression function support
• New runner labels: macos-26-large, windows-2025-vs2026
• Artifact attestations for released binaries (supply chain security)
• ./foo/bar.txt path filter now reported as error (never matches anything)
• Fixed matrix item comparison when one is a superset of another
• Fixed stack overflow crash from recursive YAML anchors
• Fixed SC2153 shellcheck false positive

v1.7.10 (2025-12-30)

• Full YAML anchors and aliases (&anchor / *alias) support — unused/undefined anchors detected
• workflow_dispatch max inputs raised from 10 → 25
• artifact-metadata permission support
• Constant if: conditions (e.g., if: true) now detected as error
• YAML merge key << reported as error (GitHub Actions doesn't support it)
• Performance: Go iterators used in workflow parser

v1.7.9 (2025-11-21)

• ubuntu-slim runner support
• Input deprecation checks via deprecationMessage metadata
• Custom images: image_version trigger + jobs.<id>.snapshot syntax
• actionlint.AllContexts constant added to Go API
• anthropics/claude-code-action added to popular actions dataset
• Deprecated: macOS 13 and *-xl runner labels removed

Go API — Rich and Underutilized

actionlint provides a comprehensive Go library that's currently unused in production code:

API	Purpose
actionlint.Linter	Full in-process linting without Docker
actionlint.Parse()	Parse workflow YAML to a typed AST
actionlint.ValidateRefGlob()	Validate branch/tag glob patterns
actionlint.ValidatePathGlob()	Validate path filter glob patterns
actionlint.PopularActions	Dataset of popular action metadata
actionlint.AllContexts	Context availability map for all workflow keys

---

Improvement Opportunities

🏃 Quick Wins

1. Pin Docker image version to match go.mod

pkg/cli/docker_images.go line 21:

// Current — can drift
ActionlintImage = "rhysd/actionlint:latest"

// Recommended — matches go.mod v1.7.11
ActionlintImage = "rhysd/actionlint:v1.7.11"

The actionlint docs explicitly note it doesn't follow semver: "any patch version bump may introduce breaking changes." Using :latest means Docker could silently upgrade between CI runs while go.mod stays pinned — an inconsistency that could cause unexpected lint failures. All three Docker image constants (ZizmorImage, PoutineImage, ActionlintImage) use :latest; the same concern applies.

2. Eliminate redundant file reads in output parser

parseAndDisplayActionlintOutput in pkg/cli/actionlint.go:390-407 reads each workflow file from disk to build context lines around the error:

fileContent, readErr := os.ReadFile(err.Filepath)
// ...builds context lines manually...

But the actionlintError struct already has a Snippet field populated from the JSON output:

type actionlintError struct {
    Snippet   string `json:"snippet"`   // already contains context!
    ...
}

The Snippet field is parsed but never used. Displaying err.Snippet directly would eliminate the disk reads entirely.

3. Fix the syntax-check docs URL mapping

getActionlintDocsURL maps "syntax-check" to check-syntax-expression — the expression check anchor. But [syntax-check] is actionlint's general YAML syntax error kind (wrong keys, missing required fields, etc.), not expression-specific. These are different checks with different docs sections. The mapping should either point to the top-level checks page or the correct syntax-check anchor.

✨ Feature Opportunities

4. In-process glob validation at compile time

The workflow compiler generates branch/tag/path glob patterns (e.g., in on.push.branches). These patterns are validated by actionlint at lint time, but could be validated immediately at compile time using:

import "github.com/rhysd/actionlint"

errs := actionlint.ValidateRefGlob("refs/heads/**/main")
errs := actionlint.ValidatePathGlob("./src/**/*.go")   // ./  prefix would be caught here!

This would catch glob errors before even writing the .lock.yml file, without needing Docker.

5. Use actionlint.AllContexts for expression validation

actionlint.AllContexts (added v1.7.9) is a map of workflow key → available context names. The compiler currently avoids generating certain needs.* expressions to prevent actionlint errors (there are comments about this in known_needs_expressions.go). Using this map in-process could make those avoidance rules more precise and maintainable.

6. Consider actionlint.Linter to eliminate Docker for actionlint

Since actionlint is already a direct Go dependency, running it in-process via actionlint.Linter would:

• Remove the Docker requirement specifically for actionlint (zizmor and poutine still need Docker)
• Eliminate the Docker image version mismatch problem
• Run faster (no container startup overhead)
• Work without a Docker daemon

This is a larger change but fits the existing tool architecture well. The JSON format parsing would be replaced by direct access to []actionlint.Error.

📐 Best Practice Alignment

7. Stderr not logged alongside parse failures

When parseAndDisplayActionlintOutput fails, the code falls back to showing raw stdout but drops stderr (pkg/cli/actionlint.go:293-297). actionlint may write diagnostic info to stderr (e.g., when shellcheck binary is missing). Showing both would help debug integration failures.

---

Recommendations (Prioritized)

1. [High impact, low effort] Pin ActionlintImage to "rhysd/actionlint:v1.7.11" — prevents silent version drift
2. [High impact, low effort] Use err.Snippet instead of re-reading files for error context display
3. [Medium impact, low effort] Fix syntax-check → docs URL mapping
4. [Medium impact, medium effort] Add actionlint.ValidateRefGlob() / actionlint.ValidatePathGlob() calls in the compiler for compile-time glob validation
5. [High impact, high effort] Evaluate replacing Docker execution with actionlint.Linter for in-process linting

---

Next Steps

• Open a PR to pin ActionlintImage to v1.7.11
• Audit the getActionlintDocsURL kind mappings against actionlint's current check list
• Prototype ValidateRefGlob() / ValidatePathGlob() integration in the compiler
• Review the new v1.7.11 checks (./ path filter errors, case() support) against generated workflow patterns

---

Module summary saved to: scratchpad/mods/actionlint.md

References:

• §23529573616
• https://github.com/rhysd/actionlint
• https://pkg.go.dev/github.com/rhysd/actionlint

AI generated by Go Fan · history

• expires on Mar 26, 2026, 7:27 AM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #23073.