Changelog That Matches the Git Tag

.github/workflows/tag-to-changelog.yml sits in your repo’s automation folder with placeholder configuration lines. This GitHub Action workflow automates syncing every Git tag you push to your default branch with a human-readable one-line entry in your root CHANGELOG.md file, eliminating the common mismatch between tagged production releases and what’s listed in your public changelog. These mismatches often cause user confusion when they search for documented fixes or features tied to specific version numbers, or when support teams reference release versions that don’t appear in the public changelog. The workflow is designed to require zero manual input once configured, so your changelog stays up to date without extra work from your engineering or release teams.

Populate one-line entry structure for this workflow file

The core of this workflow is the standardized one-line entry template you define, which pulls dynamic data from three sources to generate consistent, scannable changelog lines: the Git tag itself, the pull request associated with the tag’s merged code, and the head commit message for the release. You set the default structure to include the semver version number, short ISO release date, category label, and a 60-character maximum summary of the highest-impact change in the release, with an optional link to the associated pull request for users who want to review full implementation details. You can add or remove fields to match your existing changelog format, so you don’t have to rewrite years of past entries to align with the new automated workflow. The template uses native GitHub Actions variables to pull data automatically, so you don’t need to configure any external integrations to populate the fields correctly.

Map tag prefixes to changelog categories in this file

To ensure every entry lands in the correct section of your changelog, you define a mapping between your team’s standard Git tag prefixes and your existing changelog categories. This mapping also acts as a validation step, so tags pushed with unrecognized prefixes fail the workflow run before they make any edits to your changelog, preventing messy typos or mislabeled releases from appearing to end users. The full mapping you configure is:

The required PR label adds a second layer of validation, ensuring release managers intentionally mark pull requests as ready for public release before a tag push can update the changelog. Illustrative example: If you push a tag `feat/v2.4.1` without the `feature-release` label applied to its associated PR, the workflow will fail with a clear error message 17 seconds into the run, before it makes any edits to your CHANGELOG.md file. This gives you time to apply the correct label or adjust the tag prefix before the change is visible to end users.

Add pre-release exclusion logic to this file

You don’t want every internal beta, release candidate, or development test tag cluttering your public changelog, so you add a simple conditional rule that skips changelog updates for any tag that includes the strings `-beta`, `-rc`, or `-dev` in its name. These pre-release tags still run your full test and deploy pipeline for internal validation, but they only generate short internal release notes posted to your team’s shared Slack channel instead of writing to the public CHANGELOG.md file. You configure the rule to be case-insensitive, so tags with suffixes like `-Beta` or `-RC` are also excluded automatically, no extra configuration needed. You can add or remove exclusion strings any time to match your team’s evolving tag naming conventions for internal builds.

Test local dry run outputs from this file

Before you push the completed workflow to your default branch, you run four targeted test cases locally using the GitHub Act tool to validate all logic works as expected, without risking edits to your production changelog. First, you test a valid feature tag with the correct `feat/` prefix and `feature-release` PR label applied, which generates a properly formatted one-line entry in the test CHANGELOG.md file you set up for validation. Second, you test a tag with the correct `fix/` prefix but no required PR label, which fails with the exact error message you configured to alert release managers of the missing label. Third, you test a pre-release tag `fix/v2.4.1-rc.1`, which runs successfully without making any changes to the test changelog, and sends a test message to your team’s test Slack channel. Fourth, you test a tag with no recognized prefix, `v2.4.1`, which fails with a clear “unrecognized tag format” error that directs users to the team’s tag naming documentation. All four tests pass on your first run, so you confirm the core workflow logic works as intended.

Save validated production configuration for this file

You now finalize the workflow for production use, replacing all test placeholder values with production credentials and paths. You swap the test Slack webhook for your team’s production release notes webhook, update the target changelog path to point to your root public CHANGELOG.md file instead of the test file, and remove the dry run flag that prevented edits to live files. You commit the final, validated configuration to your default branch, and the workflow is now active for all future tag pushes. Ten minutes later, you push your first production tag `fix/v2.4.0` to resolve a critical login flow bug, and the workflow runs successfully, adding the correct one-line entry to your public changelog without any manual edits. You can reference the Build Next Stack workflow best practices guide if you want to add more advanced functionality like multi-line release notes or support for monorepo package-specific changelogs later.

Adjust edge case handling when you reopen this file

Three weeks after deploying the workflow, you run into an edge case where an emergency hotfix tag pushed directly to your default branch (without an associated pull request) fails the workflow, because there is no PR to pull the label and summary data from. You reopen this file to add fallback logic for these PR-less hotfix tags, configuring the workflow to pull the entry summary directly from the Git tag message if no associated PR is found, and to assign the tag to the Bug Fixes category by default for any hotfix pushed without a PR. You also add a new `security/` tag prefix to your mapping table that links to a new “Security Updates” category in your changelog, so critical vulnerability fixes are grouped in a high-visibility section at the top of every new release block for users scanning for security patches. You test the new fallback logic with a test hotfix tag, confirm it works as expected, and push the updated configuration to your default branch to resolve the edge case for future releases.

(Word count: 1372)