Renovate-resilient templates: split file management into bootstrap and in-place merge stages

[silug]

Problem

Renovate now manages version numbers inside files that puppetsync also manages (Gemfile gem pins, uses: actions/checkout@vN refs in GHA workflows, metadata.json dependencies). The profiles enforce those files with file { content => file(...)/epp(...) }, which overwrites unconditionally — so every puppetsync run clobbers Renovate's updates back to whatever version the template was written with.

Proposed design: split template management into two stages

Stage 1 — bootstrap (lay down complete file, only if missing)

Puppet's file resource already supports this via replace => false. Classify each managed file:

• Fully-managed (no version content — .gitignore, .rspec, _puppet-lint.rc, …): keep overwriting as today.
• Bootstrap + merge (Gemfile, GHA workflows, metadata.json, …): add replace => false so the template only seeds new repos.

Express the classification as a profile parameter (or a small profile::managed_file define) so Hiera can flip a file between modes per project type. No new pipeline stage needed — bootstrap stays inside apply_puppet_role.

Stage 2 — merge (update existing files in place, preserving Renovate-managed values and comments)

New merge_managed_files pipeline stage in plans/init.pp after apply_puppet_role, backed by one task per file family:

• merge_yaml.rb — load the existing file with psych-pure (comment/format-preserving YAML), deep-merge the template's structure into it with a declared list of preserved paths (e.g. jobs.*.steps.*.uses), write back. Add psych-pure to gem.deps.rb and the install_gems stage.
• merge_gemfile.rb — generalize the line-regexp editing already proven in tasks/configure_renovate.rb: ensure required gem lines/blocks exist, but never touch an existing version constraint.
• JSON (metadata.json, renovate.json) needs no comment preservation; JSON.parse + pretty_generate as today.

Drive the merge specs from Hiera, keyed off the existing project_types hierarchy — e.g. data/project_types/pupmod.yaml gains a puppetsync::merge_rules hash mapping file path → {type: yaml, preserve: [...]}. The "what" stays in data, the "how" in tasks.

Prior art in this repo

• profile::pupmod::gitlab_ci already implemented read-existing-file → extract repo-specific content → re-merge into template.
• tasks/configure_renovate.rb already does line-oriented Gemfile edits and JSON merging.

Risks

• psych-pure is young: before trusting it in the pipeline, add a round-trip test that parses and re-emits every workflow template under modules/profile/files/ and diffs the result. It must also install/run under Bolt's bundled Ruby.
• Workflow restructuring is the hard semantic: when a template changes a job's steps, "preserve existing uses: refs" gets ambiguous. Proposed resolution: keep the existing ref when the same step still exists; take the template's ref for genuinely new steps.

Migration

Existing repos already have all the files, so bootstrap no-ops everywhere and the merge stage becomes the workhorse immediately.

[silug]

Closed by the three-slice implementation: #70 (bootstrap strategy + profile::managed_file), #72 (merge_gemfile stage), #73 (merge_gha_workflows stage + the profile::github_actions::strategy: bootstrap flip for pupmod/pupmod_skeleton).

For the record, two places the implementation deliberately deviates from this issue's proposal — both for the better:

1. No psych-pure. Instead of a comment-preserving YAML round-trip, the workflow merger treats template text as canonical and grafts Renovate-managed values (uses, image, container, ruby-version, runs-on — extensible per session config) onto it via stdlib Psych node line/column coordinates. No re-serialization ever happens, so the round-trip risk this issue flagged is eliminated by construction, and there's no new gem to install under Bolt's Ruby. Values pair by [mapping path, key, identity], implementing exactly the "keep the existing ref when the same step still exists; take the template's ref for genuinely new steps" resolution proposed here.
2. No puppetsync::merge_rules Hiera hash. Merge behavior is driven by per-stage session config (merge_gemfile.remove_gems, merge_github_workflows.preserve_keys) plus the same per-module template fallback chains the profiles already use. The strategy classification itself is in Hiera per project_type (profile::<x>::strategy), which covers the "what lives in data" goal.

Also noted here so it doesn't get lost:

• The merge stages are opt-in: session configs must list merge_gemfile and merge_github_workflows in puppetsync.plans.sync.stages, or bootstrap-strategy files simply stay frozen. The next session config (and the latest symlink target at the next rotation) should include both.
• metadata.json, the third file family in this issue's problem statement, was never profile-managed (nothing to reclassify); its dependency-range maintenance is tracked separately in Keep metadata.json dependencies up-to-date dynamically via the Forge API (single lookup pass) #68 and Add puppet.json preset: manage metadata.json dependency ranges via the Forge API renovate-config#6.

🤖 Generated with Claude Code