Releasing semantic versions#
Semantic versioning is a formal convention for determining the version number of new software releases. The standard helps software users to understand the severity of changes in each new distribution. A project that uses semantic versioning will advertise a Major, Minor, and Patch number for each release.
Semaphore integrates with a widely used semantic versioning tool: semantic-release.
It automates the process and reduces the possibility of human errors.
sem-semantic-release is a thin
wrapper around semantic-release CLI that executes the release and exports release information. It makes
a version number available for the rest of the delivery process.
Setting up an automatic semantic release process#
To set up an automated semantic release process, you will need:
- a configured release pipeline
- a secret with necessary credentials (e.g. GitHub personal access token)
- the latest version of Node.js (it is already installed on hosted machines)
- (optional) Configuration parameters for customizing the release process
Step 1: Create a secret with the Git credentials#
The secret will contain access credentials to your repository. Go to Organizations Setting > New Secret:
- Set the name to
Add an environment variable according to the documentation here. As an example, for GitHub set the following:
- value: GitHub personal access token with repository (
Save the new secret.
The release pipeline will use this secret to connect to GitHub and generate the new release.
Step 2: Create a release pipeline#
In the main Semaphore pipeline
.semaphore/semaphore.yml define a promotion that
will trigger the automated release process:
name: Build & Test blocks: - name: Test jobs: - name: Tests commands: - checkout - make test promotions: - name: Automatic SemVer Release pipeline: release.yaml auto_promote: when: "branch = 'master' or branch =~ 'release/.*'"
Define the release pipeline in your Git repository
.semaphore/release.yml with the
name: Release blocks: - name: Release secrets: - name: semantic-release-credentials jobs: - name: Release commands: - checkout - sem-semantic-release
Step 3: Configure the release process (optional)#
Create a configuration file in the root of your repository
.releaserc to customize the release process.
The configuration options and their default values are described in
the documentation of the semantic release CLI.
sem-semantic-release uses the latest version of
semantic-release with pre-installed plugins
available in npm and its default values.
Step 4: Create a release#
Switch to the default branch in your repository, and push a new fix:
git switch main # ... make some changes to your code git commit -m "fix(pencil): stop graphite breaking when too much pressure applied" git push
The above command will trigger a new pipeline on Semaphore and generate a new patch release.
Using the release information in the continuation of your delivery process#
sem-semantic-release wraps the semantic release CLI and exports the release information to the rest
of your delivery process using sem-context put.
This information can later be retrieved with sem-context get.
It is handy when you want to continue the delivery process once the release
has been created. A common example would be to build a Docker image tagged with the release version,
or add an annotation to a Kubernetes deployment manifest.
All information is provided as string values.
Exported release information#
||Whether a new release was published (
||Version of the new release. (e.g.
||Major version of the new release. (e.g.
||Minor version of the new release. (e.g.
||Patch version of the new release. (e.g.
Example 1: Tagging a Docker image with the ReleaseVersion#
name: Release blocks: - name: Make New Release secrets: - name: semantic-release-credentials jobs: - name: Release commands: - sem-semantic-release - name: Release Docker Image secrets: - name: gcr-credentials dependencies: - Make New Release jobs: - name: Build & push docker image commands: - docker build . -t my-app:$(sem-context get ReleaseVersion) - docker push
Example 2: Tagging a Docker image and releasing a new Kubernetes version#
name: Release blocks: - name: Make New Release secrets: - name: semantic-release-credentials jobs: - name: Release commands: - sem-semantic-release - name: Release Docker Image secrets: - name: gcr-credentials dependencies: - Make New Release jobs: - name: Build & push docker image commands: - docker build . -t my-app:$(sem-context get ReleaseVersion) - docker push - name: Update Kubernetes deployment secrets: - name: gke-credentials dependencies: - Release Docker Image jobs: - name: kube apply commands: - sed -i "s/IMAGE/$(sem-context get ReleaseVersion)" deployment.yml - kubectl apply -f deployment.yml