[go-fan] Go Module Review: goccy/go-yaml

[github-actions[bot]]

🐹 This module is the backbone of gh-aw's YAML pipeline — 57 Go files import it, making it the single most widely-used third-party library in the codebase. Today's review surfaces one safety gap, a pending upstream upgrade, and several under-utilized features.

---

Module Overview

github.com/goccy/go-yaml is a pure-Go YAML library written from scratch as a superior alternative to gopkg.in/yaml.v3. Key strengths over the standard library:

• Passes ~60 more YAML Test Suite cases than gopkg.in/yaml.v3
• MapSlice for deterministic field ordering (critical for workflow diffing)
• yaml.FormatError — pretty-printed errors with source line context
• JSON-Path-style PathString queries on YAML documents
• Rich encode options: Indent, UseLiteralStyleIfMultiline, OmitEmpty, etc.

Version in use: v1.19.2 (latest release, 2026-01-08)

---

Current Usage in gh-aw

Usage Details (57 files)

Packages: pkg/workflow/, pkg/parser/, pkg/cli/

API	Where used
yaml.Marshal / yaml.Unmarshal	Throughout — round-trip encoding of workflow YAML, frontmatter, config
yaml.MarshalWithOptions(data, Indent(2), UseLiteralStyleIfMultiline(true))	yaml_options.go DefaultMarshalOptions, used in MarshalWithFieldOrder
yaml.MapSlice / yaml.MapItem	yaml.go — OrderMapFields, MarshalWithFieldOrder for deterministic field order
yaml.FormatError(err, false, true)	parser/yaml_error.go — pretty error messages with source context
yaml.EncodeOption	yaml_options.go — DefaultMarshalOptions constant

The project makes excellent use of MapSlice for deterministic GitHub Actions YAML output and yaml.FormatError for user-friendly error messages.

---

Research Findings

Recent Updates (since v1.19.2 — unreleased on master)

The repository has 4 commits on master since the v1.19.2 release (as of 2026-03-10). A v1.19.3 release is likely forthcoming:

Commit	Description	Relevance
2026-03-10	fix(token): Quote strings starting with : for Ruby/Psych YAML compatibility	⚠️ Directly relevant — GitHub Actions workflows can have values starting with :
2026-02-26	fix(encoder): Anonymous unexported struct crash	Low (no unexported anonymous structs found)
2026-02-16	Fix empty sequence item consuming sibling mapping key	Medium (edge case in workflow YAML parsing)
2026-02-16	Fix sibling anchor aliases silently resolving to nil	Low (anchors not heavily used in generated YAML)

The colon-quoting fix is notable: before this fix, a string value like :8080 would not be quoted by the encoder, causing Ruby's YAML parser (Psych) to treat it as a Symbol. This affects GitLab CI, GitHub Actions tooling, and other Ruby-based DevOps integrations.

Best Practices from Maintainers

• Prefer InterfaceMarshaler over BytesMarshaler for repeated marshaling of complex objects (avoids extra decode round-trip)
• Use yaml.NewDecoder with yaml.DisallowUnknownField() for strict user input validation
• yaml.OmitEmpty() encode option as alternative to manual nil/empty filtering

---

Improvement Opportunities

🏃 Quick Wins

1. Migrate renderStepFromMap to use yaml.MarshalWithOptions

compiler_yaml_helpers.go:337 contains a manual YAML serializer using strings.Builder. It does NOT go through goccy/go-yaml and therefore misses safe quoting for values containing :, #, or other special characters. Every other marshal path in the codebase uses ConvertStepToYAML or MarshalWithFieldOrder. The renderStepFromMap function is an inconsistency that could produce invalid YAML for edge-case step values.

// Current (unsafe for special-char values):
func (c *Compiler) renderStepFromMap(yaml *strings.Builder, step map[string]any, ...) {
    // manual fmt.Fprintf for each field
}

// Better: reuse the existing ConvertStepToYAML helper which wraps MarshalWithOptions

2. Upgrade to v1.19.3 when released

Watch for the next release that includes the colon-quoting fix. The project is currently on the latest release but master has correctness improvements. Consider pinning to master if the colon-prefix issue is observed in practice.

✨ Feature Opportunities

yaml.DisallowUnknownField() on user-facing Unmarshal calls

Calls that parse user-provided frontmatter or workflow YAML (e.g., in pkg/parser/frontmatter_content.go:63) use bare yaml.Unmarshal. Switching to yaml.NewDecoder with DisallowUnknownField() would catch typos in frontmatter keys and produce goccy's beautifully-formatted errors immediately.

// Before:
if err := yaml.Unmarshal([]byte(frontmatterYAML), &frontmatter); err != nil { ... }

// After (strict decoding):
dec := yaml.NewDecoder(strings.NewReader(frontmatterYAML), yaml.DisallowUnknownField())
if err := dec.Decode(&frontmatter); err != nil { ... }

yaml.RawMessage for deferred schema validation

Added in v1.19.0, yaml.RawMessage enables partial decoding (decode top-level structure, defer nested values). Useful in schema validation paths where only specific top-level keys need to be inspected before expensive full-document processing.

📐 Best Practice Alignment

CleanYAMLNullValues regex workaround

yaml.go:300 post-processes marshaled YAML strings with regex to strip : null. The idiomatic goccy approach for struct-based types is the omitempty struct tag or the yaml.OmitEmpty() global encode option (added v1.18.0). For the map[string]any use case the null values come from explicit nil entries — filtering them before building the MapSlice would be cleaner:

// Filter nil entries before OrderMapFields instead of post-processing:
for k, v := range data {
    if v == nil { delete(data, k) }
}

Consistent import alias

pkg/cli/compile_permissions_integration_test.go uses goyaml as the import alias while all 56 other files use the default yaml package name. Minor but worth aligning.

🔧 General Improvements

formatYAMLValue over-quotes

yaml.go:314 wraps every string value in single quotes regardless of whether quoting is needed. This is used in contexts where goccy/go-yaml isn't called for the formatting. While safe, it produces slightly noisy YAML ('true' instead of true-as-string). Consider whether these call sites could route through goccy/go-yaml's marshaling instead.

---

Recommendations (Prioritized)

1. File a tracking issue for renderStepFromMap — migrate it to use ConvertStepToYAML / yaml.MarshalWithOptions to close the unsafe-quoting gap. Low risk refactor since the test suite should catch regressions.
2. Watch for v1.19.3 and upgrade promptly for the colon-quoting fix.
3. Audit frontmatter Unmarshal calls — add yaml.DisallowUnknownField() for better user error messages on invalid keys.
4. Replace CleanYAMLNullValues with pre-marshal nil filtering as a cleanup item.

---

Next Steps

• Check if any current workflow values start with : to assess urgency of colon-quoting fix
• Review whether renderStepFromMap can be replaced with ConvertStepToYAML
• Consider adding yaml.DisallowUnknownField() to frontmatter parsing

References: §23635760496

---

Module summary saved to: scratchpad/mods/go-yaml.md

AI generated by Go Fan · history

• expires on Mar 28, 2026, 7:30 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-28T07:30:13.417Z.

Closed by Workflow