@dimension-studios/ai-changelog

AI-written release announcements for semantic-release. Generate one concise changelog message from the release diff, then publish it to Discord, Slack, or both.

Contents

• Install
• Quick Start
• Configuration
• Publishers
• Retry Notifications
• CI and Testing
• License

Install

npm install --save-dev @dimension-studios/ai-changelog

Quick Start

Add the plugin after semantic-release has generated release notes:

export default {
  branches: ["main"],
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@dimension-studios/ai-changelog",
  ],
}

Set the required CI secrets:

AI_GATEWAY_API_KEY=...
AI_CHANGELOG_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
AI_CHANGELOG_SLACK_WEBHOOK=https://hooks.slack.com/services/...

At least one publisher webhook is required unless dryRun is enabled.

Configuration

export default {
  plugins: [
    [
      "@dimension-studios/ai-changelog",
      {
        branches: ["main"],
        model: "openai/gpt-5.4-nano",
        prompt: "Write concise release notes for non-developer readers.",
        discordWebhookUrl: process.env.AI_CHANGELOG_DISCORD_WEBHOOK,
        slackWebhookUrl: process.env.AI_CHANGELOG_SLACK_WEBHOOK,
        includePaths: ["src/", "packages/"],
        excludePaths: ["packages/generated/"],
        dryRun: false,
      },
    ],
  ],
}

Required Options

At least one publisher webhook is required unless dryRun is enabled.

Optional Options

Publishers

Discord

Discord messages are sent as embeds with the generated title and description.

export default {
  plugins: [
    // ...other semantic-release plugins
    [
      "@dimension-studios/ai-changelog",
      {
        discordWebhookUrl: process.env.AI_CHANGELOG_DISCORD_WEBHOOK,
      },
    ],
  ],
}

Slack

Slack messages use Block Kit:

• header block for the generated title
• Markdown section block for the generated description
• context block with version and branch metadata
• top-level text fallback for notifications and accessibility

export default {
  plugins: [
    // ...other semantic-release plugins
    [
      "@dimension-studios/ai-changelog",
      {
        slackWebhookUrl: process.env.AI_CHANGELOG_SLACK_WEBHOOK,
      },
    ],
  ],
}

Create a Slack incoming webhook from your Slack app settings, then store the generated URL as AI_CHANGELOG_SLACK_WEBHOOK.

Discord and Slack

export default {
  plugins: [
    // ...other semantic-release plugins
    [
      "@dimension-studios/ai-changelog",
      {
        discordWebhookUrl: process.env.AI_CHANGELOG_DISCORD_WEBHOOK,
        slackWebhookUrl: process.env.AI_CHANGELOG_SLACK_WEBHOOK,
      },
    ],
  ],
}

Retry Notifications

If semantic-release succeeds but AI generation or webhook delivery fails, retry the notification without rerunning the release:

npx ai-changelog retry --branch main

By default, the retry command uses the latest reachable git tag, regenerates the AI announcement from the previous tag to that release tag, and posts to every configured publisher. Use --version for a specific release:

npx ai-changelog retry --version 1.0.1 --branch main

Retry only one publisher when the other message was already posted:

npx ai-changelog retry --version 1.0.1 --branch main --publisher slack
npx ai-changelog retry --version 1.0.1 --branch main --publisher discord

Use --dry-run to verify the generated payloads without posting:

npx ai-changelog retry --version 1.0.1 --branch main --dry-run

The retry command reads the same environment variables as the semantic-release plugin:

AI_GATEWAY_API_KEY=...
AI_CHANGELOG_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
AI_CHANGELOG_SLACK_WEBHOOK=https://hooks.slack.com/services/...

You can also override those values for a single local run with --gateway-api-key, --discord-webhook-url, and --slack-webhook-url.

GitHub Actions Retry

To make retries available from the GitHub Actions UI, add a manual workflow in your repository that checks out full git history, installs dependencies, builds the package, and runs ai-changelog retry. Expose only the retry-specific inputs operators need:

• version: leave blank to retry the latest tag, or enter a version such as 1.0.1.
• branch: the branch name shown in Slack/Discord metadata, for example main.
• publisher: both, slack, or discord.
• dry_run: preview payloads without sending webhook requests.

Use the same AI_GATEWAY_API_KEY, AI_CHANGELOG_DISCORD_WEBHOOK, and AI_CHANGELOG_SLACK_WEBHOOK secrets as your release workflow so retries use the same model and webhook configuration.

For a complete example, see this repository's retry-changelog.yml workflow.

CI and Testing

Use dryRun: true when validating the plugin in CI. The plugin still collects release context and generates notification payloads, but it does not call any webhooks.

export default {
  plugins: [
    // ...other semantic-release plugins
    [
      "@dimension-studios/ai-changelog",
      {
        dryRun: true,
      },
    ],
  ],
}

This package is verified with:

bun run check
bun run type-check
bun run knip
bun run test
bun run build

License

MIT