Installation

Prerequisites

• Git ≥ 2.30
• A repository that uses Conventional Commits

Install

Docker (recommended)

No installation needed. Pull the official image and run:

docker pull ghcr.io/semrels/semrel:latest-alpine
docker run --rm \
  -v "$(pwd):/workspace" -w /workspace \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  ghcr.io/semrels/semrel:latest-alpine release --dry-run

The alpine variant bundles git and ca-certificates — everything semrel needs. See Docker guide for image variants and version pinning.

go install

go install github.com/SemRels/semrel/cmd/semrel@latest

Requires Go ≥ 1.22. The binary is placed in $GOPATH/bin (usually ~/go/bin).

Binary download

Download the pre-built binary for your platform from GitHub Releases and place it somewhere on your $PATH:

# Linux / macOS (example for v0.2.0, amd64)
curl -L https://github.com/SemRels/semrel/releases/download/v0.2.0/semrel_0.2.0_linux_amd64.tar.gz \
  | tar xz semrel
mv semrel /usr/local/bin/
chmod +x /usr/local/bin/semrel

From source

git clone https://github.com/SemRels/semrel.git
cd semrel
go build -o semrel ./cmd/semrel
mv semrel /usr/local/bin/

Verify

semrel --version

Expected output:

semrel version v0.2.0

CI / CD

GitHub Actions (Docker)

The simplest approach — use semrel as a Docker container action. No Go toolchain required, just a checkout and the semrel step:

.github/workflows/release.yml

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run semrel
        uses: docker://ghcr.io/semrels/semrel:latest-alpine
        with:
          args: release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Or run semrel in a container job (useful when subsequent steps also need it):

jobs:
  release:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/semrels/semrel:latest-alpine
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run semrel
        run: semrel release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI (Docker)

Set the semrel image on your release job — GitLab CI runs it as the container:

.gitlab-ci.yml

semrel:
  image: ghcr.io/semrels/semrel:latest-alpine
  stage: release
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - semrel release --gitlab-dotenv semrel.env
  artifacts:
    reports:
      dotenv: semrel.env

The dotenv artifact exposes SEMREL_VERSION, SEMREL_TAG, and SEMREL_CHANGELOG to downstream jobs automatically. See CI Outputs guide for details.

GitHub Actions (go install)

Install semrel via Go toolchain if you prefer a non-Docker setup:

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'

- name: Install semrel
  run: go install github.com/SemRels/semrel/cmd/semrel@latest

- name: Run semrel
  run: semrel release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CircleCI

Use the alpine image as the executor:

.circleci/config.yml

version: 2.1
jobs:
  release:
    docker:
      - image: ghcr.io/semrels/semrel:latest-alpine
    steps:
      - checkout
      - run:
          name: Run semrel
          command: semrel release
workflows:
  release:
    jobs:
      - release:
          filters:
            branches:
              only: main

Jenkins

Use the alpine image in a declarative pipeline:

// Jenkinsfile
pipeline {
  agent {
    docker {
      image 'ghcr.io/semrels/semrel:latest-alpine'
      args  '-v $HOME/.gitconfig:/root/.gitconfig:ro'
    }
  }
  stages {
    stage('Release') {
      when { branch 'main' }
      steps {
        sh 'semrel release'
      }
    }
  }
}

Tipp

Pin your image version in production. Use ghcr.io/semrels/semrel:0.2.0-alpine instead of latest to ensure reproducible releases. See the Docker guide for all available tags.

Installing plugins from the registry

When a plugin is referenced by name and no matching binary is available locally, semrel can resolve it through the SemRels Plugin Registry.

The flow looks like this:

1. semrel checks the local plugin directory first.
2. If the binary is missing, semrel fetches registry metadata from registry.semrel.io (MVP: GitHub Pages-backed plugins.json).
3. It downloads the platform-specific release asset for the current OS and architecture.
4. It verifies the downloaded file against the published SHA-256 checksum.
5. It caches the registry metadata and binary for reuse on later runs.

By default, the registry metadata cache lives under .semrel/registry-cache, while downloaded binaries are reused from the local .semrel/ cache layout. Local binaries still take precedence, which keeps CI predictable and allows offline reuse after the first successful download.

# Optional registry overrides
export SEMREL_REGISTRY_URL=https://registry.semrel.io
export SEMREL_CACHE_DIR=.semrel
export SEMREL_CACHE_TTL=24h

For more detail, see the Plugin Registry overview and the Plugin Publishing Guide.

Shell completion

Auto-completion scripts can be generated for bash, zsh, fish, and PowerShell:

# bash
semrel completion bash > /etc/bash_completion.d/semrel

# zsh
semrel completion zsh > "${fpath[1]}/_semrel"

# fish
semrel completion fish | source