Go to Application

Configure deploy markers

4 days ago · 11 min read

Cloud

Contribute

This tutorial shows how to add a deploy marker step to your workflow config. Deploy markers allow you to log all new deployments in one place, update their status and link back to the CI/CD pipelines that triggered them.

Introduction

Deploy markers provide a lightweight way to log your deployments without requiring a you to install the CircleCI release agent. If you install deploy markers, as described in this guide, you will also be able to use the CircleCI rollback feature.

For a full guide to CircleCI’s deploys features and functionality, refer to the Deployment and deploy management guide.

You can configure deploy markers as follows:

To display updated statuses depending of the outcome of your deployments. Steps for this are provided in the Deploy markers with status updates section.
Or, you can choose to configure deploy markers to log deployments without status updates. Steps for this are provided in the Deploy logs without status updates section.

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, 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.

The circleci run release commands 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.

1.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.

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      - run: 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 you could define the target version as follows:
```
--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 you could define the target version as follows:
```
--target-version=<< pipeline.number >>
```
This configuration would yield a value with the following format 12345.

1.2. Update the deploy status to running

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.

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

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 deploy name value should match the value you provided when you planned the deploy.

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

1.3. Update the deploy status to success or failure

You can use the when attribute to add on_success and on_failure 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 \
              --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 \
              --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.

1.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 \
              --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.

1.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 --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 --status=running
      - run:
          name: Validate deployment
          command: <your-validation-logic>
      - run:
          name: Update planned deployment to SUCCESS
          command: |
            circleci run release update \
              --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 \
              --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 \
              --status=CANCELED
workflows:
  deploy-workflow:
    jobs:
      - deploy
      - cancel-deploy:
          requires:
            - deploy:
              - canceled

Deploy logs without status updates

Sometimes you might not want your deployment marker to have any specific status, but still want it 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. 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: 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 Release agent setup 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:

Set up rollbacks.

[path]

[title]