Managing Plugins

semrel installs plugins as local binaries and resolves them at runtime — no daemon, no global state. The plugin management system gives every team member and every CI runner the exact same binary, at the exact same version.

Installing a plugin project-local

1. Use the full registry reference

   Every official plugin lives in the @semrel namespace. Always include it:

   semrel plugin install @semrel/github

   A bare name (github) is only accepted when the matched registry entry has no namespace.

2. Pin a specific version when needed

   semrel plugin install @semrel/github@1.2.0

3. Commit the lock file

   A default install writes .semrel.lock at the repository root automatically. Commit it together with .semrel.yaml so everyone uses the same version.

Namespace required

semrel plugin install github fails when the plugin belongs to the @semrel namespace:

plugin "github" belongs to namespace @semrel — use:
  semrel plugin install @semrel/github

Category-prefixed names such as provider-github or condition-github-actions are resolved to their short registry names (github, github-actions) and follow the same namespace rule.

Naming and normalization

All naming variants resolve to the same binary on disk — semrel strips the namespace, version, and any category prefix before looking for an executable:

Config entry	Binary on disk
uses: github	semrel-plugin-github
uses: provider-github	semrel-plugin-github
uses: @semrel/github@1.2.0	semrel-plugin-github
uses: github-actions	semrel-plugin-github-actions
uses: condition-github-actions	semrel-plugin-github-actions

---

The .semrel.lock file new

.semrel.lock records the exact version and published checksums of every project-local plugin install. It is updated automatically whenever you run semrel plugin install without --plugin-dir.

{
  "semrelLockVersion": 1,
  "updatedAt": "2026-06-11T09:33:00Z",
  "plugins": [
    {
      "binaryName": "semrel-plugin-github",
      "ref": "@semrel/github",
      "version": "1.2.0",
      "checksums": {
        "linux_amd64":   "3b4c…",
        "linux_arm64":   "9f1e…",
        "darwin_amd64":  "c72a…",
        "darwin_arm64":  "55d0…",
        "windows_amd64": "a81b…",
        "windows_arm64": "e3f7…"
      }
    }
  ]
}

Checksums are stored for every published platform so semrel plugin restore can verify the binary on any OS/architecture without a registry round-trip.

What to commit and what to ignore

• .semrel.yaml configuration — commit
• .semrel.lock pinned plugin versions — commit
• Directory.semrel/

  • Directoryplugins/ binary cache — ignored

    • …
  • Directoryregistry-cache/ metadata cache — ignored

    • …
  • Directorylinux_amd64/ download cache — ignored

    • …
  • Directorydarwin_arm64/ download cache — ignored

    • …
  • Directorywindows_amd64/ download cache — ignored

    • …
  • …

Add these entries to your .gitignore:

# semrel — local binaries and caches (do NOT commit)
.semrel/plugins/
.semrel/registry-cache/
.semrel/linux_*/
.semrel/darwin_*/
.semrel/windows_*/
# .semrel.lock at the repo root IS committed

---

semrel plugin restore new

semrel plugin restore reads .semrel.lock, downloads every listed plugin into .semrel/plugins/, skips binaries that are already present, and verifies the checksum for the current platform.

Use this command on CI and after cloning a repository:

GitHub Actions

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up semrel
        run: |
          curl -sSL https://semrel.io/install.sh | sh
      - name: Restore semrel plugins
        run: semrel plugin restore
      - name: Release
        run: semrel release
        env:
          SEMREL_PLUGIN_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

release:
  stage: release
  script:
    - semrel plugin restore
    - semrel release
  variables:
    SEMREL_PLUGIN_TOKEN: $CI_JOB_TOKEN

Gitea Actions

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Restore semrel plugins
        run: semrel plugin restore
      - name: Release
        run: semrel release
        env:
          SEMREL_PLUGIN_TOKEN: ${{ secrets.GITEA_TOKEN }}

---

Plugin resolution order

When semrel looks up a plugin binary, it checks these locations in priority order:

1. path: in .semrel.yaml — explicit local binary, highest priority. Ideal for development or custom builds.

2. .semrel/plugins/<binary> — project-local install. Populated by semrel plugin install and semrel plugin restore.

3. ~/.semrel/plugins/<binary> — user-global install. Shared across all repositories on the machine.

4. $PATH — system-managed binary. Useful for package-manager installs.

Tip

Project-local binaries (.semrel/plugins/) take priority over the user-global directory, so different repositories can pin different plugin versions without conflict.

---

Automatic plugin restore during semrel release

semrel release checks plugin availability before doing anything else. The exact behaviour depends on whether .semrel.lock is committed:

Situation	What semrel does
All plugins present	Continue immediately — no download needed
Some plugins missing + .semrel.lock exists	Run semrel plugin restore automatically, then continue
Some plugins missing, no lock file	Attempt per-plugin auto-install (best-effort, uses latest stable)

With .semrel.lock (recommended)

$ semrel release
⬇  plugins missing — running semrel plugin restore from .semrel.lock…
✓  restored @semrel/github@1.2.0 → .semrel/plugins/semrel-plugin-github
✓  restored @semrel/github-actions@0.1.0 → .semrel/plugins/semrel-plugin-github-actions
Running condition checks…

Restore from the lock file is a hard operation: if a binary’s checksum does not match, semrel fails immediately rather than silently using a different binary.

Without .semrel.lock

If .semrel.lock is absent, semrel still attempts to auto-install each missing plugin individually. Version resolution:

1. Version from uses: — uses: github@1.2.0 pins the version explicitly.
2. Latest stable — if no version is specified, the newest non-prerelease is downloaded.

Tip

Commit .semrel.lock to get reproducible, auditable plugin installs. Without it, semrel release on a fresh machine fetches whatever version happens to be latest.

---

Installing to a different directory

Use --plugin-dir to install into a directory other than .semrel/plugins/:

# User-global install (does not update .semrel.lock)
semrel plugin install @semrel/github --plugin-dir ~/.semrel/plugins

# Custom path
semrel plugin install @semrel/github --plugin-dir /opt/semrel/plugins

Caution

Installing with --plugin-dir does not update .semrel.lock. Only default project-local installs are recorded in the lock file.

---

Plugin Overview CLI Reference Registry ↗