Plugin: hook-discord

Posts a rich release embed to Discord using an incoming webhook. Supports automatic retries on transient HTTP failures and Discord 429 rate limits, plus optional New Contributors and 🏆 Release MVP shoutouts powered by SEMREL_CONTRIBUTORS.

Installation

Binary

semrel plugin install @semrel/hook-discord

semrel plugin install downloads the binary to .semrel/plugins/ and updates .semrel.lock. Commit .semrel.lock to pin the version for your team.

Docker

Pre-built, signed multi-platform images (linux/amd64, linux/arm64) are published on every release:

docker pull ghcr.io/semrels/hook-discord:latest

Verify the image signature with cosign:

cosign verify ghcr.io/semrels/hook-discord:latest \
  --certificate-identity-regexp 'https://github.com/SemRels/hook-discord/.github/workflows/release.yml.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Configuration

version: 1
plugins:
  - uses: @semrel/hook-discord
    phase: release
    args:
      discord_webhook_url: '${env.DISCORD_WEBHOOK_URL}'
      repository: SemRels/semrel
      first_time_contributors: "true"
      release_mvp: "true"
      max_retries: "3"
      retry_delay: 2s

Environment Variables

Name	Required	Default	Description
`SEMREL_PLUGIN_DISCORD_WEBHOOK_URL`	yes (unless dry-run)	`—`	Discord incoming webhook URL.
`SEMREL_PLUGIN_REPOSITORY`	no	`—`	Repository name or URL displayed in the Discord embed fields.
`SEMREL_PLUGIN_RELEASE_URL`	no	derived	Explicit release URL for the embed title link. Derived from `SEMREL_REPOSITORY_URL` or `SEMREL_PLUGIN_REPOSITORY` when unset.
`SEMREL_PLUGIN_FIRST_TIME_CONTRIBUTORS`	no	`false`	Add a New Contributors embed field when contributor metadata is available (alias: `SEMREL_PLUGIN_NEW_CONTRIBUTORS`).
`SEMREL_PLUGIN_RELEASE_MVP`	no	`false`	Add a 🏆 Release MVP embed field for the contributor with the most commits (alias: `SEMREL_PLUGIN_MVP`).
`SEMREL_PLUGIN_MAX_RETRIES`	no	`3`	Retry count on transient network errors and HTTP `5xx` responses (`429` honours `Retry-After`).
`SEMREL_PLUGIN_RETRY_DELAY`	no	`2s`	Delay between retry attempts.
`SEMREL_PLUGIN_CONTRIBUTORS_JSON`	no	`—`	Legacy contributor JSON payload (`SEMREL_CONTRIBUTORS` from semrel core is preferred).

Release Context Variables

SEMREL_VERSION
SEMREL_TAG_NAME
SEMREL_NEXT_VERSION
SEMREL_CHANGELOG
SEMREL_CONTRIBUTORS
SEMREL_REPOSITORY_URL
SEMREL_DRY_RUN

Example Embed

When SEMREL_DRY_RUN=true, the plugin prints the JSON webhook payload to stdout without sending an HTTP request. On a live release, it posts an embed containing the release title, changelog summary, version, repository, and optional contributor shoutouts.

Source

SemRels/hook-discord