Configure release markers
This tutorial shows how to add a release marker step to your workflow config. Release markers allow you log all new releases in one place and link back to the CI/CD pipelines that caused them.
Unless you opt out of the feature, CircleCI autodetects potential releases and creates release markers for you. This guide is for you if you would rather create release markers yourself. For more information see the Releases overview page.
Release markers provide a lightweight way to log your releases without requiring a full CircleCI releases setup. You can use release markers independently, without installing the release agent. If you are interested in comprehensive release visibility and management features, refer to the Set up CircleCI releases guide for more information.
Prerequisites
-
A CircleCI account connected to your code. You can sign up for free.
-
A CircleCI project with a workflow configured to deploy your code.
1. Create environment integration
Before adding a release marker step to your workflow, you will need to create a new environment integration in the CircleCI Releases UI.
-
In the CircleCI web app, select Releases in the sidebar.
-
If this is your first environment setup, select Create your first Environment Integration. If you already have environments set up, choose the Environments tab and select Create Environment Integration.
-
Enter a name for your environment, and a description if you would like.
-
Use the dropdown menu to choose your environment integration type, then select Next: Release Agent Setup. You do not need to continue with installing a release agent at this point, but you will need to reference this environment integration name as part of your config when adding the
log releasestep below.
2. Update configuration
Next you will update your CircleCI configuration file. Add a circleci run log release command to your deployment job. This tells CircleCI to log the release marker in the Releases UI.
Add a log release step at the end of your deployment job, for example:
jobs:
deploy-my-service:
executor: some-executor
steps:
...
(existing deployment commands)
...
- circleci run release log --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name>Substitute the placeholders above based on your application’s details:
-
The
environment-nameparameter should match the name of your environment integration created via the CircleCI UI. -
The
component-nameparameter sets the name that will be displayed in the CircleCI UI. -
The
target-versionparameter should match the name of the version being released. -
(Optional) You can provide the following parameter if required:
-
The
namespaceparam can be provided to use a value other thandefault.
-
Conclusion
By following the steps in this guide, you have added a release marker to your CircleCI configuration. You can now view a log of releases in the CircleCI releases UI.