Introduce Shared YAML Dependency File To Manage Replace Directives

[blewis12]

Part of #4719

This is an initial implementation taken from the PoC for Proposal 2 from this design doc

What is included

• A basic sync-module-dependencies tool in the Alloy project that can be run with make sync-module-dependencies. The steps are broken down in a generate.go file, so each step can also be run individually
• The tool will read the dependency-replacements.yaml file located at the root of the project, transform the data, and apply it to the main go.mod file for Alloy. Note that for the time being this YAML file should not contain local replacements (e.g. we are not including the syntax module in that file in this PR)
• The output of running the tool is included in this PR - it should not be changing any replace directives in Alloy's go.mod, but it is formatting them a bit due to the generation template being structured
• There is also a GA that will check the output of running make sync-module-dependencies and check that nothing is changed in the go.mod file in pipelines, this is to ensure that the state between the YAML replacements and go.mod file(s) are aligned
• There are also some basic E2E tests, these are a bit janky - I couldn't think of a nice way to test the entire flow without basically recreating an entire test environment in a temporary directory. Maybe there's a better way

What is the intention

• I'd like to merge this change in to understand the ergonomics of using this workflow in practice. Ideally it should not change much, and should make the addition of extra modules in the future more frictionless - but i'd like to gather some feedback

What will be done as follow ups

• The current implementation only deals with go.mod file generation, not ocb yaml files - the latter will be introduced in a follow up PR. I've tried to keep things as "simple" as possible for now

Notes to Reviewers

The changes are broken down incrementally in the commits in order to make it a bit easier to understand what has been added

[github-actions]

🔍 Dependency Review

Below are the dependency changes detected in go.mod. For each, I evaluated whether code changes are required to adopt the updated state, based on version deltas and public changelogs/release notes. Collapsible details include relevant references or rationale.

github.com/open-telemetry/opentelemetry-collector-contrib/receiver/awss3receiver v0.139.0 -> v0.139.0 — ✅ Safe

• This dependency changed from indirect to direct at the same version (v0.139.0). There is no version upgrade.
• No API or behavior changes are introduced by this move alone; no code updates are required.

Evidence

• Version did not change; the module was previously present as an indirect requirement and is now explicitly required directly.
• No release delta to analyze.

No code changes required.

Notes

• This PR introduces a generator to manage “replace” directives and injects a generated block into go.mod between BEGIN/END markers. The actual replacement targets and pinned versions for forked dependencies match previous content; this is primarily a structural/automation change, not a version upgrade.
• The local replace for github.com/grafana/alloy/syntax => ./syntax is intentionally kept outside the generated block for local development.
• The added Kubernetes client-go excludes are unchanged from previous content and simply repositioned; they prevent resolution to old +incompatible versions.
• Several indirect entries were removed from require; these do not indicate a downgrade or removal of transitive functionality—Go will still pull them if needed during build.

[Copilot]

Pull request overview

This PR introduces a centralized YAML-based system to manage Go module replace directives across the repository. The tool reads from dependency-replacements.yaml, generates formatted replace directives, and automatically injects them into target go.mod files between generated markers. This streamlines dependency management and ensures consistency across modules.

Key Changes

• Centralized dependency configuration: All replace directives are now defined in dependency-replacements.yaml at the project root
• Automated generation pipeline: A multi-step Go generate pipeline (generate → apply → tidy → cleanup) processes the YAML and updates target files
• CI validation workflow: GitHub Actions workflow ensures go.mod files stay synchronized with the YAML source

Reviewed changes

Copilot reviewed 15 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
dependency-replacements.yaml	New centralized YAML file defining all replace directives with comments
tools/sync-module-dependencies/internal/types/types.go	Type definitions for YAML parsing and module configuration
tools/sync-module-dependencies/internal/helpers/files.go	File path resolution and YAML loading utilities
tools/sync-module-dependencies/internal/generate-replaces.go	Template-based generation of replace directive text files
tools/sync-module-dependencies/internal/apply-replaces.go	Logic to inject generated blocks into target files using markers
tools/sync-module-dependencies/internal/tidy-modules.go	Runs go mod tidy on affected modules
tools/sync-module-dependencies/internal/cleanup.go	Removes temporary .txt files after generation
tools/sync-module-dependencies/replaces-mod.tpl	Template for formatting go.mod replace directives
tools/sync-module-dependencies/generate.go	Orchestrates the generation pipeline via go generate
tools/sync-module-dependencies/e2e_test.go	E2E tests covering new block insertion and existing block updates
tools/sync-module-dependencies/go.mod	Module definition for the sync tool
tools/sync-module-dependencies/go.sum	Dependency checksums for the sync tool
tools/sync-module-dependencies/README.md	Documentation explaining usage, configuration, and troubleshooting
go.mod	Updated with generated replace directives between markers
Makefile	Adds sync-module-dependencies target and integrates it into local build workflow
.gitignore	Excludes temporary .txt files from version control
.github/workflows/check-sync-module-dependencies.yml	CI workflow validating go.mod synchronization
tools/sync-module-dependencies/resources/flow_diagram.png	Visual diagram of the generation pipeline (binary file)

[thampiotr]

Looking solid! Got a few comments on how we could maybe simplify it if possible to make it leaner.

[thampiotr]

We have several main functions declared in one package, could we avoid this? most IDEs will complain and some go commands that operate on entire package will fail I think

[thampiotr]

One good alternative could be to use Cobra to create a tool with a few subcommands.

[thampiotr]

We could also create a testdata/... folder and put there an example project that we can check into the repo. Might be easier to read and get a feel for the tool this way.

[blewis12]

I quite like that, i'll do some exploration there