Configure deploy markers

Cloud

This tutorial shows how to add deploy markers to your CircleCI configuration file.

Deploy markers enable you to log all new deployments in one place, update their status and link back to the CI/CD pipelines that triggered them. You can also get set up to rollback and deploy from the CircleCI web app.

Introduction

Deploy markers provide a lightweight way to log your deployments. Once you have deploy markers configured, you will see a timeline of deployments in the Deploys UI. From the timeline you have the following options:

Rollback to a version ().
Promote (deploy) a version ().
Get notifications for failed deployments.

Figure 1. Deploys timeline with failed deployment

Figure 2. Deploys timeline with no deployments requiring troubleshooting

Deploy markers also enable you to use the rollback and deploy features:

Rollback pipelines: Manually revert to a previous version of a component from the CircleCI web app. See the Set up Rollbacks guide for more details.
Deploy pipelines - Automatically deploy a new version of a component from the CircleCI web app. See the Set up Deploys for more details.

Choose your setup method

You can set up deploy markers in two ways:

Set up deploy markers from the web app: Use the CircleCI web app to set up deploy marker configuration for a single project or multiple projects at once.
- With AI features enabled, CircleCI generates the configuration for you.
- Without AI features you receive a configuration template to apply manually.
Set up deploy markers manually: Edit your CircleCI configuration file directly to add deploy markers. You can choose to configure deploy markers with status updates or without status updates.

You can also set up deploy markers using AI as part of the rollback or deploy pipeline guided setup process. See the Set up Rollbacks or Set up Deploys guides for more details.

Set up deploy markers from the web app

You can set up deploy markers for a single project or for multiple projects at once from the CircleCI web app. With AI features enabled, CircleCI uses AI to analyze your existing pipeline configurations and generate the required deploy marker commands. See the Enable AI-Powered Features page for steps to enable AI features.

Prerequisites

Your code must be stored in a GitHub repository.
A CircleCI account connected to your code. You can sign up for free.
A CircleCI project with a workflow configured to deploy your code.
Organization admin permissions in CircleCI (required for multi-project setup).
The GitHub App installed in your organization. If not installed, the setup process prompts you to install it.
AI features enabled for your organization (required for AI-based generation). See the Enable AI-Powered Features page for steps. If AI features are not enabled, you are presented with a configuration template instead of AI-generated configuration. You can copy the template and use it to update your configuration files manually.

1. Start the setup

You can start the deploy marker setup from project or organization settings, depending on whether you are setting up deploy markers for a single project or multiple projects:

Single project
Multiple projects

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis next to your project and select Project Settings.

You can also access project settings from each project overview page using the Settings button.
Select Deploys in the sidebar.
Select Configure deploy markers in the Deploy Markers card.

Project Deploy Settings page showing the Deploy Markers card with Configure deploy markers button

Figure 3. Project Deploy Settings page with the option to configure deploy markers

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Org from the sidebar.
Select Deploys.
Select Configure Deploy Markers.

Figure 4. Organization Deploy Settings page with the option to configure deploy markers
A modal displays a list of the projects you follow. Select the projects you want to add deploy markers to, or select the Select all checkbox, then select Continue.

Figure 5. Select projects for deploy marker setup

Only projects you follow are shown. To follow more projects, select the Follow more projects link at the top of the modal.

2. Generate and commit configuration

Single project
Multiple projects

Follow the steps in-app to get set up. For more information on the process, see the Set up a Rollback Pipeline guide which includes the same process.

On the next page, you see a table of your selected projects with their repository and branch information. CircleCI auto-detects the branch where possible. If a branch is not auto-detected, select one from the dropdown menu.

Configuration generation page showing selected projects with repository and branch details and Generate buttons

Figure 6. Generate deploy marker configuration for selected projects

You have two options for generating the configuration:

Select Generate next to an individual project to generate the deploy marker configuration for that project only.
Select Generate all configs at the bottom of the page to generate configurations for all selected projects at once.

Once the configuration is generated, select Commit changes to GitHub to commit the changes to a branch in your repository. After the commit is made, a view link appears so you can review the changes on GitHub.

Generation will fail for a project in the following cases:

The project already has deploy markers configured.
The project does not have a deployment job in its configuration.

Set up deploy markers manually

This section covers how to set up deploy markers by editing your CircleCI configuration file directly. You can configure deploy markers with or without status updates:

With status updates: Track the full lifecycle of your deployments (pending, running, success, failed, canceled).
Without status updates: Log deployments in the deploys UI without tracking their status.

The circleci run release commands are part of the CircleCI environment CLI. They are only available in CircleCI builds and are not part of the CircleCI local CLI. You do not need to install the CircleCI local CLI in your CircleCI pipeline to use these commands. See also the full Environment CLI Usage Guide.

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.

Deploy markers with status updates

To create a deployment marker with status updates, you will update your CircleCI configuration file. You will add commands to plan a deploy and then update its status based on the outcome of your deployment script.

We recommend configuring circleci run release plan and circleci run release update in the same job. If you configure these commands in different jobs, you must ensure any reruns are made using the Rerun workflow from start option, not Rerun workflow from failed. This is because rerunning from failed in this scenario will cause subsequent update operations to fail.

1. Plan a deploy

Add a circleci run release plan command to your deployment job. This tells CircleCI to plan a new deploy and show it in the Deploys UI with pending status.

Plan your deployment

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      - run:
          name: Plan deployment
          command: |
            circleci run release plan <deploy-name> \
              --environment-name=<some-environment-name> \
              --component-name=<some-component-name> \
              --target-version=<some-version-name> \
              --namespace=<some-namespace>

In this example, note the following flags and options:

The <deploy-name> argument is used to identify the deployment. deploy-name is an arbitrary positional argument that will be used to identify the deployment and should be unique within the workflow. If not specified, the deployment name will be set to default. If you are deploying multiple components or to multiple environments from a single workflow, you need to provide the command with a deployment name.
The --environment-name flag sets the target environment. If the specified environment does not exist, it will be created. If you do not specify an environment, CircleCI will create one named default.
The --component-name flag sets the name that will be displayed in the Deploys UI. If you do not already have a component in your project a new one will be created with the name of the project. This will be set as the component that is being deployed.
The --target-version flag should match the version being deployed. Some examples are provided in the next section.
The --namespace flag is optional and can be provided to use a value other than default.

Configuring circleci run release plan identifies the deployment you are planning so that you can reference it to update its status later on.

Examples for target-version

This section provides some options for setting the target-version parameter.

One option is to use CircleCI’s built-in environment variables. For example, define the target version as follows:
Example of setting target version using CircleCI’s built-in environment variables
```
--target-version="1.0.${CIRCLE_BUILD_NUM}-${CIRCLE_SHA1:0:7}"
```
This configuration would yield a value with the following format 1.0.28853-ffdbeb1.
Another option is to use pipeline values. For example, define the target version as follows:
```
--target-version=<< pipeline.number >>
```
This configuration would yield a value with the following format 12345.

2. Update the deploy status to running

The circleci run release update command is only for use with deploy markers. If you are using the CircleCI release agent for Kubernetes deployments, do NOT use the update commands. The release agent automatically handles status updates for you. See the Release Agent Overview page for more details.

After deploying your application, you can update the status of the deployment to RUNNING by running the circleci run release update command in a new step.

If you specified a deploy-name when planning your deploy, remember to provide your deploy name when using the update commands too. The deploy name value should match the value you provided when you planned the deploy. If you did not provide a deploy name when you planned the deploy, it will be set to default and you do not need to provide it when updating the status.

Update the deploy status to running

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      ...
      (existing deployment commands)
      ...
      - run: circleci run release update <deploy-name> --status=running

3. Update the deploy status to success or failure

You can use the when attribute to add on_success and on_fail steps at the end of your deployment job, to handle the final status update of the deploy.

Config file example showing deploy status update to success or failure

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      ...
      (existing deployment commands)
      ...
      - run:
          name: Update planned release to SUCCESS
          command: |
            circleci run release update <deploy-name> \
              --status=SUCCESS
          when: on_success
      - run:
          name: Update planned release to FAILED
          command: |
            if [ -f failure_reason.env ]; then
              source failure_reason.env
            fi
            circleci run release update <deploy-name> \
              --status=FAILED \
              --failure-reason="$FAILURE_REASON"
          when: on_fail

In this example, the status of the deploy is updated to SUCCESS or FAILED depending on the outcome of your job.

The failure_reason.env file can be created by a previous step in the job. This can be done, for example, in a step in which we are validating the status of the deployment. One way to do this is as follows:

Create a file to store the failure reason

echo "FAILURE_REASON='Deployment was not found'" > failure_reason.env

Trying to update the status of the deploy after updating it to a terminal status such as SUCCESS, FAILED or CANCELED is not supported and will result in an error.

4. Update the deploy status to canceled

If you want to update your deployment to canceled when the deploy job is canceled, you can do so by adding the following job to your configuration.

Job configuration for updating the deploy status to canceled

jobs:
  deploy:
    ...
    (deploy job steps)
    ...
  cancel-deploy:
    executor: go
    steps:
      - run:
          name: Update planned release to CANCELED
          command: |
            circleci run release update <deploy-name> \
              --status=CANCELED

Then you can add it to your workflow as shown below.

Workflow configuration for updating the deploy status to canceled. The cancel-deploy job only runs when the deploy job is canceled

workflows:
  deploy-workflow:
    jobs:
      - deploy
      - cancel-deploy:
          requires:
            - deploy:
              - canceled

In this example, the cancel-deploy job will be run only when the deploy job is canceled, thus updating the deployment to the canceled status.

5. Full config example

For reference, here is a full example of a CircleCI config that makes use of the deployment tracking feature.

version: 2.1

jobs:
  deploy:
    executor: go
    steps:
      - checkout
      - run:
          name: Plan deployment
          command: |
            circleci run release plan <deploy-name> \
              --target-version=<some-version-name>
      - run:
          name: Perform deployment
          command: <your-deployment-logic>
      - run:
          name: Update planned deployment to running
          command: circleci run release update <deploy-name> --status=running
      - run:
          name: Validate deployment
          command: <your-validation-logic>
      - run:
          name: Update planned deployment to SUCCESS
          command: |
            circleci run release update <deploy-name> \
              --status=SUCCESS
          when: on_success
      - run:
          name: Update planned deployment to FAILED
          command: |
            if [ -f failure_reason.env ]; then
              source failure_reason.env
            fi
            circleci run release update <deploy-name> \
              --status=FAILED \
              --failure-reason="$FAILURE_REASON"
          when: on_fail
  cancel-deploy:
    executor: go
    steps:
      - run:
          name: Update planned release to CANCELED
          command: |
            circleci run release update <deploy-name> \
              --status=CANCELED
workflows:
  deploy-workflow:
    jobs:
      - deploy
      - cancel-deploy:
          requires:
            - deploy:
              - canceled

Deploy marker logs without status updates

Sometimes you might not want your deploy markers to have any specific status, but still want them to be logged in the deploys UI. In those cases you can use the release log command in place of release plan as shown in the example below.

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      ...
      (existing deployment commands)
      ...
      - run: circleci run release log --target-version=<some-version-name>

This command supports the same optional parameters as the release plan command, but does not require a deploy-name.

If you are deploying to multiple environments from a single workflow, you need to specify the target environment using the --environment-name flag. If you are deploying multiple components from a single workflow, you need to specify the component name using the --component-name flag.

You can see the command with all optional parameters in the following example:

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      ...
      (existing deployment commands)
      ...
      - run:
          name: Log release
          command: |
            circleci run release log \
              --environment-name=<some-environment-name> \
              --component-name=<some-component-name> \
              --target-version=<some-version-name>

The --environment-name flag specifies the target environment. If the environment does not exist, it will be created.
The --component-name flag sets the name that will be displayed in the CircleCI UI.
The --target-version flag should match the name of the version being deployed. Some examples are provided above.
(Optional) You can provide the following parameter if required:
- The --namespace flag can be provided to use a value other than default.

Manage environments

In this guide we created an environment integration by supplying a name with the --environment-name flag. This was an optional step. If you did not specify an environment CircleCI will have created one for you with the name default.

You can also create an environment integration manually in the CircleCI web app.

Create an environment integration

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Deploys in the sidebar.
Select the Environments tab.
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. Choose the "Custom" option to follow along with this guide,. If you are deploying to your Kubernetes cluster you can or if you want to use the CircleCI release agent, then choose "Kubernetes Cluster" and head over to the Set up the CircleCI Release Agent page.
Select Save and Continue.

Next steps

By following the steps in this guide, you have added a deploy marker to your CircleCI configuration. You can now track the status of your deployments across your configured environments in the CircleCI deploys UI and in the project home page. You can now:

[path]

[title]

Configure deploy markers

Introduction

Choose your setup method

Set up deploy markers from the web app

Prerequisites

1. Start the setup

2. Generate and commit configuration

Set up deploy markers manually

Prerequisites

Deploy markers with status updates

1. Plan a deploy

Examples for target-version

2. Update the deploy status to running

3. Update the deploy status to success or failure

4. Update the deploy status to canceled

5. Full config example

Deploy marker logs without status updates

Manage environments

Create an environment integration

Next steps