tapiau/semantic-release

•Updated 6 months ago

Image

1.1K

tapiau/semantic-release repository overview

⁠semantic-release (Go)

A Go reimplementation of semantic-release⁠ — fully automated version management and package publishing based on commit messages.

Instead of deciding manually whether a release is 1.1.0 or 2.0.0, semantic-release reads your commit history and computes the next version automatically using the Conventional Commits⁠ convention.

⁠How it works

Commit type	Version bump
`fix: …`	patch → `1.0.1`
`feat: …`	minor → `1.1.0`
`feat!: …` or `BREAKING CHANGE:` footer	major → `2.0.0`

On every run the tool executes a 9-step pipeline:

verifyConditions — check tokens and CI environment
getLastRelease — find the last git tag
analyzeCommits — determine bump type from commits since last tag
verifyRelease — validate the upcoming release
generateNotes — build changelog / release notes
createTag — create and push the git tag
prepare — update files (CHANGELOG.md, etc.)
publish — create platform releases (GitLab, …)
notify — success / failure callbacks

Each step is handled by one or more plugins executed in order.

⁠Usage

⁠Docker (recommended — no Go required)

docker run --rm \
  -v "$(pwd)":/repo \
  -w /repo \
  -e GL_TOKEN=<your-token> \
  ghcr.io/semantic-release-go/semantic-release

⁠Dry run (preview only, no tags created)

docker run --rm \
  -v "$(pwd)":/repo \
  -w /repo \
  -e GL_TOKEN=<your-token> \
  ghcr.io/semantic-release-go/semantic-release --dry-run

⁠Flags

Flag	Description
`--dry-run` / `-d`	Preview mode — no tags, no publish
`--debug`	Verbose logging
`--no-ci`	Allow running outside a CI environment
`--tag-format`	Git tag format (default: `v${version}`)
`--repository-url`	Override git remote URL
`--version` / `-v`	Print version and exit

⁠Configuration

Create .releaserc.yml in your repository root:

branches:
  - main
  - master
  - name: beta
    prerelease: true

tagFormat: "v${version}"

plugins:
  - commit-analyzer
  - release-notes-generator
  - changelog
  - coretag
  - "@semantic-release/gitlab"

Supported config file names (in lookup order):

.releaserc (YAML or JSON)
.releaserc.json
.releaserc.yml / .releaserc.yaml
package.json (key "release")

⁠Built-in plugins

Plugin name	Hook	Description
`commit-analyzer`	analyzeCommits	Parse Conventional Commits, determine bump type
`release-notes-generator`	generateNotes	Generate Markdown release notes grouped by type
`changelog`	prepare	Create / update `CHANGELOG.md`
`coretag`	createTag	Create annotated git tag and push to remote
`git`	prepare	Commit release assets back to the repository
`exec`	any	Execute shell commands at lifecycle hooks
`gitlab`	verifyConditions, publish	Create GitLab Releases via API

Plugin names are also accepted with the @semantic-release/ prefix for compatibility with existing configs.

⁠Branch management

Three branch types are supported:

branches:
  - main                          # release branch
  - name: next
    channel: next                 # release on "next" dist-tag
  - name: beta
    prerelease: true              # 1.2.0-beta.1, 1.2.0-beta.2, …
  - name: "1.x"
    range: "1.x.x"               # maintenance branch

⁠Authentication

Environment variable	Purpose
`GL_TOKEN` / `GITLAB_TOKEN`	GitLab API + git push
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub git push
`GIT_CREDENTIALS`	Generic HTTPS (`user:token`)
`GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`	Commit author identity

⁠GitLab CI example

release:
  stage: release
  image: <your-registry>/semantic-release:latest
  variables:
    
    GIT_DEPTH: 0
  script:
    - /app/semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

⁠Building from source

Go 1.22+ is required only inside the Docker build — nothing needs to be installed locally.

# Build Docker image
make build

# Run tests
make test

# Interactive shell in the builder container
make shell

⁠Architecture

cmd/semantic-release/     CLI entrypoint
pkg/
  config/                 Config file loader (.releaserc YAML/JSON)
  plugin/                 Hook interfaces, Context, plugin registry
  semver/                 SemVer 2.0 parser and version calculator
internal/
  analyzer/               Conventional Commits parser + bump logic
  branch/                 Branch type classification
  ci/                     CI environment detection + auth helpers
  git/                    Git operations (go-git, no system git required)
  workflow/               9-step orchestrator + plugin runner
  plugins/
    changelog/            CHANGELOG.md writer
    coretag/              Git tag creator + pusher
    exec/                 Shell command executor
    git/                  Release asset committer
    gitlab/               GitLab Releases API client
    notes/                Markdown release notes generator

See doc/ for architecture decision records and feature reference.

⁠Why Go instead of Node.js?

The original semantic-release requires Node.js and installs hundreds of MB of node_modules in CI. This implementation compiles to a single static binary (~15 MB) with no runtime dependencies — drop it into any alpine or scratch container.

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:3718ced53…

Size

20.1 MB

Last updated

6 months ago

docker pull tapiau/semantic-release