Monorepo Support

semrel supports repositories that contain multiple independently versioned modules. Each module has its own version history, its own tag series, and its own .semrel.yaml.

Repository layout

Directorymy-monorepo/
- Directoryservices/
  - Directoryapi/
    .semrel.yaml
    go.mod
  - Directoryworker/
    .semrel.yaml
    go.mod
- Directorylibs/
  - Directorycore/
    .semrel.yaml
    go.mod

Each component has its own .semrel.yaml and is released independently.

Tagging convention

In a monorepo, semrel prefixes every tag with the module path:

services/api/v1.4.0
services/worker/v0.9.1
libs/core/v2.0.0

This means git log --tags gives you a clean per-module history without any cross-contamination.

Per-module configuration

Each module’s .semrel.yaml is fully independent. You can configure different bump rules, different branches, or different plugins per module:

version: 1

branches:
  - name: main

release:
  rules:
    - type: feat
      bump: minor
    - type: fix
      bump: patch

plugins:
  - name: github
    args:
      owner: MyOrg
      repo: my-monorepo
      # The release is scoped to the services/api subfolder
      tag_prefix: services/api/

Running releases

Run semrel from the module directory, or use --config to point at a module config:

# From the module root
cd services/api
semrel release

# Or from the repo root
semrel release --config ./services/api/.semrel.yaml

CI example (GitHub Actions)

jobs:
  release-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required: semrel needs full git history
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go install github.com/GoSemantics/semrel/cmd/semrel@latest
      - run: semrel release --config ./services/api/.semrel.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}