Plugin Overview

semrel plugin ecosystem showing providers, conditions, analyzers, generators, updaters, packagers, publishers, and hooks connected to the core release pipeline

semrel’s release pipeline is composed of standalone plugin executables. Each plugin is discovered locally and executed as a subprocess — there is no gRPC layer or RPC handshake.

How plugins work

semrel reads each plugin entry from .semrel.yaml.
The uses: value resolves to a binary named semrel-plugin-<name> after semrel strips any namespace, version, or category prefix.
semrel looks for that binary at an explicit path:, then in .semrel/plugins/, then in ~/.semrel/plugins/, then in $PATH.
Plugin args: values are exposed as environment variables in the form SEMREL_PLUGIN_<KEY>=<value>.
Release context is also passed through environment variables so every plugin can read the same version, branch, tag, changelog, and dry-run state.
semrel runs the executable and uses the process result to continue or stop the pipeline.

Release context environment

These environment variables are available to plugin processes during execution.

Variable	Description
`SEMREL_VERSION`	Resolved release version for the current run
`SEMREL_TAG_NAME`	Full tag name for the release
`SEMREL_CURRENT_VERSION`	Current project version
`SEMREL_NEXT_VERSION`	Next version selected for the release
`SEMREL_BUMP`	Calculated bump level
`SEMREL_BRANCH`	Current git branch
`SEMREL_TAG_PREFIX`	Configured tag prefix
`SEMREL_CHANGELOG`	Generated changelog content
`SEMREL_DRY_RUN`	Whether the current run is a dry run

Plugin types

The current official plugin catalog is organized into eight categories.

Provider Plugin

Handles forge and git operations such as reading release history, creating tags, and publishing releases.

Condition Plugin

Verifies that the current environment is allowed to publish a release.

Analyzer Plugin

Inspects commits and decides the SemVer bump level.

Generator Plugin

Produces changelogs, release notes, and other release-facing content.

Updater Plugin

Updates versioned project files before the release is finalized.

Packager Plugin

Builds distributable artifacts such as Linux packages from prepared release inputs.

Publisher Plugin

Publishes release artifacts to OCI registries and generic HTTP endpoints.

Hook Plugin

Sends notifications or runs follow-up automation after success or failure.

What about Go binaries, Docker/Podman images, Helm, and similar targets?

These targets are supported today with a split model: updaters prepare versioned project metadata, while packaging and publishing can run through dedicated plugins and CI jobs.

Target	Current plugins	What they do today	Typical next step
Go binaries	`updater-go`	Updates Go version variables before release tagging.	Build binaries in CI with `go build` and then package/publish artifacts.
Docker/Podman images	`updater-docker`	Updates Dockerfile version arguments.	Build images in CI with Docker or Podman, then publish image artifacts.
Helm charts	`updater-helm`	Updates `Chart.yaml` version and optional `appVersion`.	Package and publish charts in CI or OCI-compatible registries.
Linux packages	`packager-nfpm`	Builds `deb`, `rpm`, and `apk` packages via `nfpm`.	Publish generated packages to your package channels.
Generic/OCI artifacts	`publisher-generic-http`, `publisher-oci`	Uploads release artifacts to HTTP endpoints or OCI registries.	Chain publishers after build/package stages.

Plugin discovery

Discover official plugins in the Plugin Registry, install them with semrel plugin install <ref>, and use the Managing Plugins guide for lock files and restore workflows.

semrel resolves plugins from the configured uses: value:

plugins:
  - uses: github
    name: github-release
    args:
      owner: MyOrg
      repo: my-repo

  - uses: slack-notify
    path: /usr/local/bin/semrel-plugin-slack
    args:
      webhook_url: ${{ env.SLACK_WEBHOOK }}

Plugin lifecycle

Next steps

Official Plugins Managing Plugins Plugin Registry Migration Guide Write a Plugin