Configure deploy markers

Cloud

Deploy markers provide a lightweight way to log your deployments without requiring a full CircleCI deploys setup. You can use deploy markers independently, without installing the release agent. If you are interested in comprehensive deployment visibility and management features, refer to the Set up CircleCI deploys 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. Update the configuration

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.

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. The target-version parameter should match the name of the version being deployed.

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      - run: circleci run release plan --target-version=<some-version-name>

If you do not have an environment set up in your organization a new one will be created with the name default. This will be set as the target for this deploy. See 3. Manage environments for more information.

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.

If you already have multiple environments and components you must specify their names manually, as follows:

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

In this example, note the following:

The environment-name parameter sets the target environment. If the specified environment does not exist, it will be created.
The component-name parameter sets the name that will be displayed in the Deploys UI.
The namespace parameter is optional and can be provided to use a value other than 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. This identifies the deployment your are planning so that you can later on reference it to update its status. This can be done as shown below:

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>

In the example the positional argument deploy-name is the arbitrary value 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.

1.2. Update the deploy status

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

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

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

This will update the status of the deploy to SUCCESS or FAILED depending on the outcome of your job. In this example, 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. You can do that as shown below:

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

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

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.

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

This will make it sot that the job will be run only when the deploy job is canceled, thus updating the deployment to the canceled status.

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

2. Deploy logs

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

3. Manage environments

Configuring deploy markers will automatically create an environment integration in the CircleCI deploys UI with the name you specified or with the default name if you didn’t specify any. You can then use the CircleCI UI to manage your environments, by creating, deleting or updating them. To manually create an environment integration, follow these steps:

In the CircleCI web app, select Deploys 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. If you plan to only use deploy markers, as opposed to the Kubernetes agent, feel free to choose the custom type. 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 release step below.

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: