Add merge_gha_workflows task and pipeline stage (#50 slice 3)

[silug]

Final slice of #50: refresh GHA workflow files from their baseline templates while preserving every Renovate-managed value already in the repo. Independent of #70/#72 (disjoint files; the stage anchors next to configure_renovate (immediately before it) specifically to avoid overlapping #72's diff) — but the three together complete the issue.

Cleaner than planned: no psych-pure

The issue proposed a psych-pure comment-preserving round-trip. This implementation avoids re-serialization entirely: since downstream workflow files are stamped copies of the templates, the template text is canonical — structure, comments, formatting, byte-for-byte — and the Renovate-managed scalars are grafted back onto it using stdlib Psych's node line/column coordinates (surgical rest-of-line replacement). Comment/format preservation holds by construction, and there's no new gem to install or trust.

Semantics

• preserve_keys (default: uses, image, container, ruby-version, runs-on; extensible via the session config's merge_github_workflows.preserve_keys) selects which mapping keys carry Renovate-managed values. The defaults cover the real-world cases from pupmod-simp-pupmod: dd98340 (ruby-version: 3.2 → 3.4.9) and 837fb5e (runs-on: ubuntu-20.04 → ubuntu-24.04), plus action refs and container images.
• Pairing is by [mapping path, key, identity], where identity is the part Renovate never changes (actions/checkout@v5 → actions/checkout; ghcr.io/x/y:8 → ghcr.io/x/y; bare versions → none). So: distinct versions per job survive independently; trailing comments ride along (pinned-digest conventions keep the human-readable version there); steps genuinely new to — or restored by — the template take the template's value, per the policy in the issue.
• Scope discipline: the merge_github_workflows stage merges only files present in both the repo and the template chain (same per-module override resolution as profile::github_actions). Creating and removing workflow files stays the profile's job, and repo-specific workflows with no template are never touched.

Verification

• 13 specs, several driven by the real pr_tests.yml template, including byte-identity assertions ("output equals template except the grafted lines") and cases for pinned-digest comments, per-job version divergence, restored jobs, multi-file invocations, and idempotency. 167 examples total, 0 failures.
• End-to-end against a file:// fixture whose pr_tests.yml had Renovate bumps (checkout@v7, ruby-version: 3.4.9, ubuntu-24.04) and structural drift, plus an untemplated custom.yml: the merge restored template structure, preserved all 6+5+6 bumped values, left custom.yml untouched, and run 2 reported 0 ok / 1 unchanged / 0 failed. (A deliberately bumped value inside a commented-out template job was correctly reverted to template text — comments belong to the template.)
• puppet parser validate --tasks, bolt plan show, stage-list dry run, CI idempotency e2e all green. No CHANGELOG edit per the freeze.

Completing #50

Once this and #70 merge, the closing move is a one-line Hiera flip (profile::github_actions::strategy: bootstrap per project_type) plus closing the issue — I'd fold that into whichever merges last, or a tiny follow-up.

Refs #50

🤖 Generated with Claude Code

[nick-markowski]

Really like this approach — grafting managed values onto canonical template text via Psych node coordinates is clean, and using Psych.parse (AST only, not load/unsafe_load) means there's no object-instantiation surface from untrusted workflow YAML. The pairing by [path, key, identity] with sequence indices excluded is sound: steps reorder safely, per-job version divergence survives, and new/restored steps correctly fall through to the template value. Rest-of-line capture carries pinned-digest trailing comments verbatim, it's idempotent, and the byte-identity-except-grafts invariant is asserted directly. Approving, with two things:

1. Drop the warn stdin debug line (same as #72) — it dumps the full JSON input, including every workflow template, to stderr on each run.

2. Make the Hiera-flip dependency explicit — the stage is inert without it. It runs after apply_puppet_role (line 183), and while profile::github_actions is still enforce, that stage overwrites each workflow with pure template first — so this stage then reads template-equals-existing and no-ops, with the Renovate values already enforced away upstream. So enabling merge_github_workflows before the profile::github_actions::strategy: bootstrap flip protects nothing; the stage and the flip have to land together. Worth tying them explicitly (config docs / a note) so nobody enables it pre-flip expecting preservation.

Minor: identity() returns nil for a ported registry (registry:5000/foo:8) since [\w.-]+ excludes //:, so it'd pair per-key positionally instead of by image — unlikely in GHA, fine to leave. And the body says the stage anchors "after configure_renovate" but it's inserted just before it — immaterial, just a note.

Everything else — coordinate grafting, multi-line skip, malformed/empty handling, plan scoping, template resolution — checks out.

[silug]

All addressed in 144716f:

1. warn stdin dropped.
2. The flip now ships with the stage — you're right that they're inseparable: with the profile still enforcing, apply_puppet_role overwrites each workflow with pure template before this stage runs, so pre-flip enablement protects nothing. profile::github_actions::strategy: bootstrap is now set for pupmod/pupmod_skeleton in data/project_types/ (the exact scope the merge stage covers — rubygem/unknown_with_ci stay enforce since the stage doesn't run for them). The key is inert until Add bootstrap mode for managed baseline files (#50 slice 1) #70's strategy support merges (Hiera automatic lookup only consults declared params), and it activates the moment both are in — so merge order doesn't matter. The stage comment documents the coupling.
3. Minor Initial hacks to get pdk convert --force running #1 taken too since it was cheap: identity() now handles ported registries (registry:5000/foo:8 pairs by everything before the tag colon), with a spec. Minor Rollup add_gce and de-jirafication #2: correct — the stage sits immediately before configure_renovate, not after; PR body fixed.

12 examples, 0 failures.

🤖 Generated with Claude Code