Migrating from semantic-release

Delete .releaserc.json, the plugins in package.json and the npx semantic-release step. Each plugin maps to built-in behavior or one input.

semantic-release plugin	releaser
`commit-analyzer` (conventionalcommits)	Built in. `releaseRules` → `rules`.
`release-notes-generator` (conventionalcommits)	Built in, same section layout.
`changelog`	Built in, always `CHANGELOG.md`.
`npm` (version bump only)	Built in: `package.json` `version` is bumped. Nothing is published.
`exec` `prepareCmd`	`prepare`, with `${nextRelease.version}` → `${version}`.
`git` `assets`	`CHANGELOG.md` and `package.json` built in, the rest via `commit`.
`github` `assets`	`artifacts`.
`github` `draftRelease: true`	`draft: true`.
`tagFormat: "v${version}"`	Always `v${version}`.
`branches: ["main"]`	`branch`, default `main`.

Example

This .releaserc.json:

{
  "branches": ["main"],
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "conventionalcommits",
        "releaseRules": [
          { "breaking": true, "release": "patch" },
          { "type": "feat", "release": "patch" },
          { "type": "docs", "release": "patch" },
          { "type": "refactor", "release": "patch" }
        ]
      }
    ],
    [
      "@semantic-release/release-notes-generator",
      { "preset": "conventionalcommits" }
    ],
    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "bun scripts/bump-version.ts ${nextRelease.version} && bun run package:extension"
      }
    ],
    ["@semantic-release/git", { "assets": ["CHANGELOG.md", "package.json"] }],
    [
      "@semantic-release/github",
      {
        "assets": [
          {
            "path": "dist/extension.zip",
            "name": "extension-${nextRelease.version}.zip"
          }
        ]
      }
    ]
  ],
  "tagFormat": "v${version}"
}

becomes:

- uses: orochibraru/releaser@v1
  with:
    rules: breaking=patch,feat=patch,docs=patch,refactor=patch
    prepare: bun scripts/bump-version.ts ${version} && bun run package:extension
    artifacts: dist/extension.zip=extension-${version}.zip

Reading the next version first

To stamp images or binaries with the upcoming version before the real release, run a dry run first:

- id: next
  uses: orochibraru/releaser@v1
  with:
    dry-run: "true"
# steps.next.outputs.version is the upcoming version, empty if nothing to release

Differences

Overrides merge with the defaults per key. semantic-release instead ignores the defaults for a commit once any custom rule matches it.
One release branch; no maintenance channels. Prereleases are one id on that branch (canaries), not a branch per channel.
No npm publish. Run it in prepare, or in a later step gated on steps.<id>.outputs.released.
Outside CI the CLI is a dry run, like semantic-release's --no-ci guard.

← Previous

Inputs and Flags

Release Flows

This guide lives in the project repo: edit it there, and this page follows within a day.