Agentic Automation: Automated Releases and Changelog

At Medusa, we're automating our internal operations with AI to increase our efficiency. We're applying this across engineering, documentation, sales, and other operations. This has allowed us to dedicate our resources to shipping features faster for our users.

So, we're starting a series of posts around the different agentic automations we have built. These posts will share how these processes work and our learnings from them.

Check out our previous post in the series on up-to-date skills and MCP server.

Problem: Manual Release Flows Across Products

For the past few years, releasing a new version of Medusa required a set of manual steps to prepare different aspects of the release. That included publishing the release, documenting it, testing it, drafting release notes, designing release images for our changelog, and more.

However, this process takes a long time and is prone to human error. For example, we spend too much time on manually writing the release notes for big releases, often forgetting features. We may also forget to add a release image, which affects the look and feel of our changelog.

The work around this increased as we added Medusa Cloud releases into the mix, which had its own release flows. We still wanted to showcase these changes as new releases and part of the same changelog we have for Medusa open source.

How We Solved this with Agentic Automation

To solve this problem, we built different agentic automations with the tools they can use to make this process much quicker and free of human errors. This allows to spend more time on shipping features and refining our products.

The next sections explain the different pieces in the flow.

Updating Documentation

Ahead of a release, we have a PR that includes all the documentation updates necessary for the new release. This PR is opened and authored by Claude Code. Whenever we merge a change into the Medusa repository (which is only released when we publish a new release), an automation flow uses Claude Code to:

1. Find what changed in the source code.
2. Translate that into documentation changes, such as updating existing doc entries or adding new ones.
3. Either open the PR if there isn't an existing one, or push changes to the existing PR.

You can learn more about this automation flow and how it helps us create reliable and accurate docs in the Up-to-Date Docs with Agentic Automation post.

Drafting Release Notes

For Medusa open source, we release a new version of our packages by merging a release PR. Once it's merged and a new version is out, we trigger another GitHub action to draft the release notes.

This action uses Claude Code to draft these release notes. We have a skill to write release notes based on our guidelines, including what to mark as a breaking change, when to include code snippets, and how to list the full list of changes and new contributors. Claude Code looks through all commits, picks out those that are either worth highlighting as a new feature, or breaking changes that must be mentioned in the release notes, and uses them to draft the release notes.

Then, we review the release notes to make sure everything is correct. Once it's good to go, we publish the release on GitHub, which triggers other parts of the release flow as explained next.

Generating Changelog Info

The changelog available at https://medusajs.com/changelog is sourced from our GitHub releases so that we don't have to maintain the same information in multiple places. However, to make it more presentable for our website, we require an image, a title, and a description to show in the list.

We set this information at the beginning of the GitHub release notes in a comment block similar to the following:

12345678910
<!--

![v2.19.0](https://res.cloudinary.com/dza7lstvk/image/upload/v1786545698/Releases/v2-19-0.png)

# v2.19.0: Vite v7 Update, Inventory Export, Custom Fulfillment Addresses

v2.19.0 updates the Medusa Admin dashboard to use Vite v7, supports exporting inventory data as CSV, passing custom fulfillment address, and more.

CMS_BREAK -->

Part of the release notes skill that we pass to Claude Code includes the semantics of adding this comment block to the release notes. So, Claude Code generates the title and description that are fitting for our website's changelog.

As for the image, we built a tool on top of Satori that uses the same template for releases, replacing the release version with the current release number, and uploading it to Cloudinary. Claude Code then uses the generated image in the comment block.

The changelog entry then shows these information generated by Claude Code once the release is published.

Other Non-Agentic Automations

The release process includes other automated flows that don't use agents, including:

1. Automated tests for preview releases: Before we release a new latest version of Medusa packages, we release a Copy to clipboardpreview version for testing purposes. Once it's released, it triggers an automation that deploys the preview version to a test project on Medusa Cloud, and reports any errors in the deployments on Slack. This allows us to catch any overlooked issues that can potentially affect our users when they update.
2. Reference Documentation Updates: Our documentation has API references for store and admin routes, workflow SDK, UI library, and more. These are generated with custom tools we've built based on our docs and code infrastructure. Once we publish a new release, it triggers multiple automations that re-generate these references based on the published source code and opens PRs with the changes.

Automation for Medusa Cloud Releases

Medusa Cloud changes are published in a separate flow and repository than Medusa open source. That doesn't stop us from automating its flow to publish release notes on those changes across channels.

When a new release is published, we trigger a GitHub action in the Medusa open source project that, aside from updating the documentation with the latest changes, adds a new changelog entry with a summary of what changed. We use Claude Code to generate that summary based on the source code of the released changes.

Then, we display that changelog in two places:

1. In the documentation, where the changelog entries actually live.
2. In the changelog page, alongside the Medusa Open Source changelog entries. Similarly, we generate a release image as part of the flow that uses a unified template, changing the release date.

We have other automatically generated changelog for Medusa Cloud, including changelog for the Cloud CLI and Webhooks. These follow the same process and use Claude Code to write the changelog notes, but without an entry in the main website changelog.

View Automation Flow

Most of our automation flow lives in the docs-automator tool in our open source repository. It shapes inputs coming from different sources into Claude Code prompts that are used to make changes to the documentation.

When a Medusa open source release is published on NPM, it triggers the draft-release GitHub action that drafts the release notes for us to review, with all the changes mentioned earlier. Similarly, a Medusa Cloud release triggers the cloud-docs-automation GitHub action to update the Medusa Cloud documentation and add the changelog entries.

Get Started with Medusa

If you're new to Medusa, check out the documentation, where you'll get a more in-depth understanding of what Medusa is, the commerce features it provides, and how to deploy Medusa to Cloud.