Awesome
:package::rocket: semantic-release
fully automated package/module/image publishing
This project aims to be an alternative to the original semantic-release implementation. Using Go, semantic-release
can be installed by downloading a single binary and is, therefore, easier to install and does not require Node.js and npm. Furthermore, semantic-release
has a built-in plugin system that allows to extend and customize its functionality.
Features
- Automated version and release management
- No external dependencies required
- Runs on Linux, macOS and Windows
- Fully extensible via plugins
- Automated changelog generation
- Supports GitHub, GitLab and git
- Support for maintaining multiple major version releases
How does it work?
Instead of writing meaningless commit messages, we can take our time to think about the changes in the codebase and write them down. Following the Conventional Commits specification it is then possible to generate a helpful changelog and to derive the next semantic version number from them.
When semantic-release
is setup it will do that after every successful continuous integration build of your default branch and publish the new version for you. This way no human is directly involved in the release process and your releases are guaranteed to be unromantic and unsentimental.
Source: semantic-release/semantic-release#how-does-it-work
You can enforce semantic commit messages using a git hook.
Installation
Option 1: Use the go-semantic-release GitHub Action (go-semantic-release/action)
Option 2: Install manually
curl -SL https://get-release.xyz/semantic-release/linux/amd64 -o ./semantic-release && chmod +x ./semantic-release
Option 3: Install via npm
npm install -g go-semantic-release
Examples
Releasing a Go application with GitHub Actions
Full example can be found at go-semantic-release/example-go-application.
Example .github/workflows/ci.yml config:
name: CI
on:
push:
branches:
- '**'
pull_request:
branches:
- '**'
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: 1.19
- uses: golangci/golangci-lint-action@v3
test:
runs-on: ubuntu-latest
needs: lint
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: 1.19
- run: go test -v ./...
release:
runs-on: ubuntu-latest
needs: test
permissions:
contents: write
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: 1.19
- uses: go-semantic-release/action@v1
with:
hooks: goreleaser
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Example GitLab CI Config
GitLab token
It is necessary to create a new Gitlab personal access token with the api
scope here.
Ensure the CI variable is protected and masked as the GITLAB_TOKEN
has a lot of rights. There is an open issue for project specific tokens
You can set the GitLab token via the GITLAB_TOKEN
environment variable or the -token
flag.
.gitlab-ci.yml
stages:
# other stages
- release
release:
image:
name: registry.gitlab.com/go-semantic-release/semantic-release:latest
entrypoint: [""]
stage: release
# when: manual # Add this if you want to manually create releases
only:
- master
script:
- semantic-release # Add --allow-no-changes if you want to create a release for each push
Job Token
If you do not provide a PAT the job token will be used. This restricted token can create releases but not read commits. The git strategy must be set to clone so that we can read the commits from the repository. See example below
.gitlab-ci.yml
variables:
GIT_STRATEGY: clone
stages:
# other stages
- release
release:
image:
name: registry.gitlab.com/go-semantic-release/semantic-release:latest
entrypoint: [""]
stage: release
# when: manual # Add this if you want to manually create releases
only:
- master
script:
- semantic-release
# - semantic-release --allow-no-changes # create a release for each push
# - semantic-release --provider gitlab --provider-opt log_order=ctime # traverse commits by committer time (commits in merge requests will affect the calculated version)
Releasing a Go application with GitLab CI
The full example can be found at https://gitlab.com/go-semantic-release/example-go-application.
Example .gitlab-ci.yml config:
image: golang:1.19
stages:
- test
- release
test:
stage: test
except:
- tags
script:
- go test -v ./...
- go build ./
- ./example-go-application
release:
stage: release
only:
- main
script:
- curl -SL https://get-release.xyz/semantic-release/linux/amd64 -o ./semantic-release && chmod +x ./semantic-release
- ./semantic-release --hooks goreleaser
Plugin System
Since v2, semantic-release is equipped with a plugin system. The plugins are standalone binaries that use hashicorp/go-plugin as a plugin library. semantic-release
automatically downloads the necessary plugins if they don't exist locally. The plugins are stored in the .semrel
directory of the current working directory in the following format: .semrel/<os>_<arch>/<plugin name>/<version>/
. The go-semantic-release plugins registry (https://registry.go-semantic-release.xyz/) is used to resolve plugins and to download the correct binary. With the new plugin-registry service the API also supports batch requests to resolve multiple plugins at once and caching of the plugins.
Running semantic-release in an air-gapped environment
As plugins are only downloaded if they do not exist in the .semrel
folder, it is possible to download the plugins and archive the .semrel
folder. This way it is possible to run semantic-release
in an air-gapped environment.
# specify all required plugins and download them
./semantic-release --download-plugins --show-progress --provider github --ci-condition github --hooks goreleaser
# archive the .semrel folder
tar -czvf ./semrel-plugins.tgz .semrel/
# copy the archive to the air-gapped environment
# extract the archive
tar -xzvf ./semrel-plugins.tgz
# run semantic-release
./semantic-release --provider github --condition github --hooks goreleaser
Plugins
- Provider (Docs)
- CI Condition (Docs)
- Commit Analyzer (Docs)
- Changelog Generator (Docs)
- Hooks (Docs)
- Files Updater (Docs)
Configuration
Plugins can be configured using CLI flags or the .semrelrc
config file. By using a @
sign after the plugin name, the required version of the plugin can be specified. Otherwise, any locally installed version will be used. If the plugin does not exist locally, the latest version will be downloaded. This is an example of the .semrelrc
config file:
{
"plugins": {
"commit-analyzer": {
"name": "default@^1.0.0"
},
"ci-condition": {
"name": "default"
},
"changelog-generator": {
"name": "default",
"options": {
"emojis": "true"
}
},
"provider": {
"name": "gitlab",
"options": {
"gitlab_projectid": "123456"
}
},
"files-updater": {
"names": ["npm"]
}
}
}
Beta release support
Beta release support empowers you to release beta, rc, etc. versions with semantic-release
(e.g. v2.0.0-beta.1). To enable this feature you need to create a new branch (e.g. beta/v2) and check in a .semrelrc
file with the following content:
{
"maintainedVersion": "2-beta"
}
If you commit to this branch a new incremental pre-release is created everytime you push. (2.0.0-beta.1, 2.0.0-beta.2, ...)
Licence
Copyright © 2024 Christoph Witzko