Multi-Repo Aggregated Changelog Prompt Template

This prompt is designed for platform teams and release managers who must coordinate a single, coherent release across three or more interdependent repositories. The core job-to-be-done is transforming a collection of per-repo change summaries, a dependency map, and version constraints into a unified changelog. The ideal user is an engineering lead or release manager who already has the raw data from each team but needs to resolve cross-repo ordering, shared breaking change impact, and coordinated version bump recommendations without manual aggregation errors.

You should use this prompt when your repositories have runtime or build-time dependencies on each other, meaning a change in one repo can break or alter the behavior of another. The prompt requires structured inputs: a list of per-repo change summaries, a dependency graph showing which repos depend on which, and any version constraints or release policies. Do not use this for single-repo changelogs, which are better served by a simpler diff-to-release-note prompt. It is also inappropriate when repositories are fully independent and share no release cadence, as the coordination logic adds unnecessary complexity and may introduce false dependency relationships.

Before using this prompt, ensure you have a clear dependency map and that each per-repo summary is accurate and complete. The prompt's value comes from its ability to order entries by dependency chain, highlight breaking changes that propagate across repos, and recommend a single set of version bumps that respects semver across the entire ecosystem. If your inputs are incomplete or the dependency map is stale, the output will be unreliable. Pair this prompt with a validation step that checks the generated changelog against the source summaries and dependency graph to catch ordering errors or missing cross-repo impacts before publication.

The following prompt template is designed to be pasted directly into your AI system. It expects a structured list of repository change summaries as input and produces a single, unified changelog. The prompt instructs the model to order entries by cross-repo dependency, highlight shared breaking changes, and recommend coordinated version bumps. Before execution, you must replace every square-bracket placeholder with real data from your release pipeline.

textCopy
You are a release automation engineer. Your task is to generate a unified, multi-repository changelog from a structured list of per-repo change summaries.

[INPUT]
The input is a JSON array of repository change objects. Each object has the following schema:
{
  "repo_name": "string",
  "current_version": "string (semver)",
  "changes": [
    {
      "category": "feat | fix | breaking | deprecation | security | docs | chore",
      "description": "string (one sentence)",
      "commits": ["string (short SHA)"],
      "related_issues": ["string (issue ID)"],
      "dependency_of": ["string (repo_name)"] // repos that depend on this change
    }
  ]
}

[INPUT_DATA]
```json
[INSERT_PER_REPO_CHANGE_ARRAY_HERE]

[CONSTRAINTS]

1. Group entries under the following sections: Breaking Changes, Features, Security Fixes, Bug Fixes, Deprecations, Documentation, and Dependencies.
2. Within each section, order entries by cross-repo impact. A change that is listed as a dependency_of another repo must appear before the dependent change.
3. For each breaking change, add a **Migration Required** note that lists all affected repositories.
4. Generate a **Coordinated Version Bump Recommendation** table at the top. The table must have columns for Repository, Current Version, Recommended Version, and Bump Reason. The bump reason must reference specific breaking changes or feature additions.
5. If a change has no related_issues, omit the issue reference. If a change has no dependency_of entries, treat it as a standalone change.
6. Do not invent or summarize changes not present in the input data. If a repository has no changes, omit it from the changelog.

[OUTPUT_SCHEMA] Return a single JSON object with this exact structure: { "release_title": "string (generated from the most significant feature or breaking change)", "version_bump_table": [ { "repository": "string", "current_version": "string", "recommended_version": "string", "bump_reason": "string" } ], "sections": [ { "section_name": "Breaking Changes | Features | Security Fixes | Bug Fixes | Deprecations | Documentation | Dependencies", "entries": [ { "description": "string (user-facing changelog line)", "affected_repos": ["string"], "commits": ["string"], "issues": ["string"], "migration_note": "string | null" } ] } ] }

[EXAMPLES] Input: [ { "repo_name": "auth-service", "current_version": "2.1.0", "changes": [ { "category": "breaking", "description": "Deprecated legacy token endpoint POST /v1/token", "commits": ["a1b2c3d"], "related_issues": ["AUTH-421"], "dependency_of": ["api-gateway", "user-dashboard"] } ] }, { "repo_name": "api-gateway", "current_version": "3.0.1", "changes": [ { "category": "feat", "description": "Added support for new auth token format", "commits": ["e4f5g6h"], "related_issues": ["GW-112"], "dependency_of": [] } ] } ]

Output: { "release_title": "Auth Service Legacy Token Deprecation and Gateway Token Format Update", "version_bump_table": [ { "repository": "auth-service", "current_version": "2.1.0", "recommended_version": "3.0.0", "bump_reason": "Breaking change: deprecated legacy token endpoint" }, { "repository": "api-gateway", "current_version": "3.0.1", "recommended_version": "3.1.0", "bump_reason": "Feature: support for new auth token format" } ], "sections": [ { "section_name": "Breaking Changes", "entries": [ { "description": "Deprecated legacy token endpoint POST /v1/token in auth-service", "affected_repos": ["auth-service", "api-gateway", "user-dashboard"], "commits": ["a1b2c3d"], "issues": ["AUTH-421"], "migration_note": "Migration Required: api-gateway and user-dashboard must update to use the new token endpoint before upgrading auth-service." } ] }, { "section_name": "Features", "entries": [ { "description": "Added support for new auth token format in api-gateway", "affected_repos": ["api-gateway"], "commits": ["e4f5g6h"], "issues": ["GW-112"], "migration_note": null } ] } ] }

[RISK_LEVEL] This is a documentation-generation task. The primary risk is hallucinating changes or misrepresenting breaking change impact. Always validate the output against the input data before publishing.

To adapt this template for your pipeline, replace [INSERT_PER_REPO_CHANGE_ARRAY_HERE] with the aggregated output of your per-repo diff analysis. The dependency_of field is the linchpin for correct ordering; ensure your upstream tooling populates it by parsing import graphs, API client configurations, or service dependency manifests. If you cannot determine dependencies automatically, run the prompt without ordering constraints and flag the output for manual reordering by a release manager. The OUTPUT_SCHEMA is designed to be machine-readable so you can pipe the result directly into documentation sites or Slack release announcements after validation.

Before integrating this prompt into a CI pipeline, build a validation step that diffs the generated commits list against the input commits. Any commit SHA in the output that does not appear in the input is a hallucination and must block the release note artifact. For high-risk releases, route the generated JSON through a human approval queue where a release manager can verify the version_bump_table recommendations and migration_note accuracy before the changelog is published to users.

The multi-repo aggregated changelog prompt is designed to run as a batch job triggered by a release coordinator, not as a real-time user-facing feature. It consumes structured inputs from multiple repository CI pipelines—commit logs, diff summaries, and dependency manifests—and produces a unified changelog artifact. The implementation harness must enforce input freshness, validate cross-repo consistency, and gate the output behind human review before publication. Treat this prompt as a composable step in a larger release workflow, not a standalone generator.

Input assembly is the first critical integration point. Build a pre-processing script that collects the latest tagged release commit SHA from each repository, fetches the commit range since the last aggregated release, and extracts conventional commit messages, breaking change annotations, and dependency graph updates. Feed these into the prompt's [REPO_CHANGE_MANIFESTS] placeholder as a structured JSON array, with one object per repository containing repo_name, version_bump, commits, breaking_changes, and dependency_updates fields. Validate input completeness before invoking the model: if any repository manifest is missing or stale (older than the last aggregated release timestamp), abort and alert the release coordinator. Use a model with a large context window (200K+ tokens) and strong structured output capabilities, such as claude-sonnet-4-20250514 or gpt-4o, to handle the combined manifest size. Set response_format to json_schema with the expected changelog schema to enforce output structure.

Post-generation validation is mandatory. Implement a multi-pass verification harness: (1) Schema check—validate the JSON output against the expected changelog schema, rejecting missing required fields or malformed entries. (2) Cross-repo consistency check—verify that dependency ordering in the changelog matches the submitted dependency graph; flag any entry that references a change from a repository not included in the input manifests. (3) Breaking change impact audit—for every breaking change listed, confirm that the affected consumer repositories are explicitly mentioned in the impact section. (4) Hallucination detection—diff the generated changelog entries against the source commit messages; flag any feature description or bug fix that cannot be traced to at least one commit SHA. If validation fails, retry once with the validation errors appended to the [CONSTRAINTS] section as explicit correction instructions. If the retry also fails, route the partial output and error report to a human release manager for manual completion.

Human approval and publication complete the harness. After validation passes, post the aggregated changelog draft to a review channel (Slack, email, or internal release dashboard) with a structured summary: number of repositories included, breaking change count, dependency upgrade count, and a link to the full draft. Require explicit approval from at least one repository maintainer per affected repo before the changelog is published to external-facing channels. Store the final approved changelog as a versioned artifact in your release registry, tagged with the aggregated release version and the commit SHA range it covers. Log every step—input assembly timestamps, model invocation parameters, validation results, retry attempts, and approver identity—to maintain an audit trail for compliance and debugging. Avoid running this prompt on every commit; trigger it only on coordinated release events to prevent noise and reviewer fatigue.