Release Note Automated CI Pipeline Prompt Template

This prompt is built for DevOps and platform engineering teams that need to generate release notes as a deterministic, auditable step inside a CI/CD pipeline. The ideal user is an engineer wiring AI into GitHub Actions, GitLab CI, Jenkins, or a similar system where the input is a structured git log and the output must be a validated, categorized release note artifact. The job-to-be-done is not ad-hoc summarization; it is producing a pipeline stage that can be called programmatically, pass automated accuracy gates, and fail cleanly when the input is insufficient.

Use this prompt when your commit history follows a conventional commit format or can be pre-processed into a structured log with fields like type, scope, and description. The prompt expects [COMMIT_LOG] as a structured input, [TARGET_VERSION] for the release tag, and optional [PREVIOUS_VERSION] for diff scoping. It produces a categorized release note with sections for features, fixes, breaking changes, and dependency updates. Do not use this prompt for unstructured commit messages, repositories without commit discipline, or one-off changelog drafts that require creative prose. It is not a general-purpose summarizer and will produce unreliable output when the input format contract is violated.

Before adopting this prompt, verify that your pipeline can supply the required structured input and that your team has defined the accuracy gates the output must pass. Common gates include diff-to-claim grounding checks, category misclassification detection, and hallucination flagging against source commits. If your release process requires human approval before publication, wire the prompt output into a review step rather than auto-publishing. For repositories with inconsistent commit quality, invest in a pre-processing stage that normalizes messages before they reach this prompt.

This prompt template is designed to be wired directly into your CI runner after the commit log and diff summary have been assembled. It takes structured inputs representing the changes since the last release and produces a formatted release note draft. The template uses square-bracket placeholders for all dynamic inputs, making it safe for string interpolation in pipeline scripts without conflicting with model-specific token syntax. Before integrating, ensure your pipeline has already filtered commits to the relevant release window and generated a concise diff summary.

textCopy
You are a technical release manager generating user-facing release notes.

Generate release notes from the provided commit history and code diff summary.

## Inputs

### Commit History
[COMMIT_HISTORY]

### Diff Summary
[DIFF_SUMMARY]

### Previous Release Tag
[PREVIOUS_TAG]

### New Release Tag
[NEW_TAG]

## Output Schema

Return a JSON object with the following structure:

{
  "release_version": "string",
  "release_date": "YYYY-MM-DD",
  "summary": "string (1-2 paragraph overview of the release)",
  "categories": [
    {
      "name": "Features | Bug Fixes | Breaking Changes | Deprecations | Security | Dependencies | Documentation | Internal",
      "entries": [
        {
          "description": "string (user-facing description of the change)",
          "commits": ["string (abbreviated commit hash)"],
          "contributors": ["string (author handle)"],
          "issue_refs": ["string (e.g., #123)"]
        }
      ]
    }
  ],
  "breaking_changes": [
    {
      "description": "string (detailed description of the breaking change)",
      "migration_guidance": "string (steps users must take to adapt)",
      "affected_surfaces": ["string (API endpoint, function name, config key, etc.)"]
    }
  ],
  "upgrade_instructions": "string (step-by-step upgrade procedure)",
  "known_issues": [
    {
      "description": "string",
      "workaround": "string or null"
    }
  ]
}

## Constraints

1. Every entry in `categories` must be grounded in at least one commit from [COMMIT_HISTORY] or a change described in [DIFF_SUMMARY].
2. Do not invent features, bug fixes, or breaking changes not present in the inputs.
3. If no breaking changes are detected, `breaking_changes` must be an empty array.
4. Use Conventional Commit prefixes (feat:, fix:, BREAKING CHANGE:, etc.) to categorize entries when available.
5. Group related commits into a single entry when they address the same feature or fix.
6. Write descriptions in past tense, active voice, targeting a developer audience.
7. If [DIFF_SUMMARY] indicates changes to public APIs, schemas, or configuration formats, explicitly flag them for breaking change review.
8. If the inputs contain insufficient information for a field, use an empty string or empty array as appropriate—never hallucinate content.

## Risk Level
[RISK_LEVEL]

If [RISK_LEVEL] is "high", append a `review_notes` field to the output JSON containing a list of claims that require human verification before publication.

To adapt this template for your pipeline, replace each square-bracket placeholder with the corresponding data from your CI context. [COMMIT_HISTORY] should contain the formatted log of commits between [PREVIOUS_TAG] and [NEW_TAG], ideally with abbreviated hashes, author handles, and full message bodies. [DIFF_SUMMARY] should be a concise summary of the aggregated code diff, focusing on public API changes, schema modifications, configuration updates, and dependency version bumps. [RISK_LEVEL] should be set to "high" for major releases, security patches, or any release touching authentication, authorization, data persistence, or public APIs. When risk is high, the additional review_notes field in the output ensures a human must sign off on specific claims before the release note is published. Always validate the model's output against your source commits and diffs using the evaluation criteria defined in the testing section of this playbook before merging into your release branch.

This prompt is designed to run as a step in a CI/CD pipeline triggered by a version tag or a merge to a release branch. The harness should execute the prompt after the build and test stages succeed, ensuring the codebase is in a known good state before generating documentation. The primary integration points are the git history input, the generated release note artifact, and the downstream approval or publishing system. The prompt expects structured input—a git log between two refs, parsed conventional commit messages, and any associated issue tracker references—so the harness must assemble this context before invoking the model.

Build the harness as a script or pipeline job that first collects the commit range using git log [PREVIOUS_TAG]..HEAD --pretty=format:'%h %s %b' and passes it into the prompt's [COMMIT_HISTORY] placeholder. After the model returns the draft release note, run a deterministic validation step: parse the output against the expected [OUTPUT_SCHEMA] (e.g., a JSON object with version, date, categories, and entries arrays) and reject malformed responses. Implement a diff-based accuracy gate by extracting all commit SHAs referenced in the generated note and verifying each exists in the source commit range. Flag any hallucinated SHAs or entries that cannot be traced to a source commit. For high-risk releases, add a mandatory human approval step: post the draft as a pull request comment or a Slack notification with a link to a review interface, and block publication until an authorized reviewer approves.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, and set response_format to json_object if the provider supports it. Set a retry policy: if validation fails, retry once with the same prompt plus the validation error message appended as [CONSTRAINTS] feedback. If the second attempt also fails, fail the pipeline job and alert the release manager. Log every prompt invocation, the raw model response, validation results, and the final approved artifact to an audit trail. Store the approved release note as a versioned artifact in the repository (e.g., CHANGELOG.md or a dedicated /releases directory) and push it to the documentation site or package registry as the final pipeline step. Avoid running this prompt on every commit—trigger it only on release events to control cost and noise.