--- title: "Configure deploy markers" description: "Tutorial outlining how to configure deploy markers in your workflow." doc_version: "unversioned" last_updated: "2026-08-12" --- > For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Configure deploy markers 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. > **Image:** Deploy timeline with failed deployment Figure 1. Deploys timeline with failed deployment > **Image:** Deploys timeline with no deployments requiring troubleshooting 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](https://circleci.com/docs/guides/deploy/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](https://circleci.com/docs/guides/deploy/set-up-deploys/) for more details. ## Choose your setup method **Consider using Smart Deployments instead of this guide.** The Smart Deployments guided setup configures deploy markers, rollback and deploy pipelines, release validation, and automatic rollback. When AI features are enabled and the CircleCI GitHub App is installed, CircleCI opens a single pull request for you to merge. See the [Set up Smart Deployments](https://circleci.com/docs/guides/deploy/set-up-smart-deployments/) guide and its [Setup routes](https://circleci.com/docs/guides/deploy/set-up-smart-deployments/#setup-routes) section. Use this page when you want deploy markers on their own. Also use it when your code is not in a GitHub repository, when your organization does not have AI features enabled, or when you prefer to edit YAML directly. You can set up deploy markers in two ways: * [Set up deploy markers from the web app](#set-up-deploy-markers-for-multiple-projects): 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](#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](#deploy-markers-with-status-updates) or [without status updates](#deploy-marker-logs-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](https://circleci.com/docs/guides/deploy/set-up-rollbacks/) or [Set up Deploys](https://circleci.com/docs/guides/deploy/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](https://circleci.com/docs/guides/toolkit/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](https://circleci.com/signup/). * 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](https://circleci.com/docs/guides/toolkit/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: 1. In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage. 2. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help. 3. 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. 4. Select **Deploys** in the sidebar. 5. Select **Configure deploy markers** in the Deploy Markers card. > **Image:** 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 1. In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage. 2. Select **Org** from the sidebar to open your organization settings page. 3. Select **Deploys**. 4. Select **Configure Deploy Markers**. > **Image:** Organization Deploy Settings page showing the Configure Deploy Markers button Figure 4. Organization Deploy Settings page with the option to configure deploy markers 5. 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**. > **Image:** Project selection modal showing a list of followed projects with checkboxes 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 Follow the steps in-app to get set up. For more information on the process, see the [Set up a Rollback Pipeline](https://circleci.com/docs/guides/deploy/set-up-rollbacks/#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. > **Image:** 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](#deploy-markers-with-status-updates): Track the full lifecycle of your deployments (pending, running, success, failed, canceled). * [Without status updates](#deploy-marker-logs-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](https://circleci.com/docs/guides/toolkit/environment-cli-usage-guide/). ### Prerequisites * A CircleCI account connected to your code. You can [sign up for free](https://circleci.com/signup/). * 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**. Rerunning from _failed_ in this scenario causes 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](https://app.circleci.com/deploys) with `pending` status. Plan your deployment ```yml jobs: deploy-my-service: executor: some-executor steps: - run: name: Plan deployment command: | circleci run release plan \ --environment-name= \ --component-name= \ --target-version= \ --namespace= ``` In this example, note the following flags and options: * The `` argument is used to identify the deployment. `deploy-name` is an arbitrary positional argument that will be used to identify the deployment and must 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 must match the version being deployed. Some examples are provided [in the next section](#examples-for-target-version). * 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 ```yml --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: ```yml --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](https://circleci.com/docs/guides/deploy/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 must 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 ```yml jobs: deploy-my-service: executor: some-executor steps: ... (existing deployment commands) ... - run: circleci run release update --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 ```yml 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 ```yml 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 ```yml 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 ```yml 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. ```yml version: 2.1 jobs: deploy: executor: go steps: - checkout - run: name: Plan deployment command: | circleci run release plan \ --target-version= - run: name: Perform deployment command: - run: name: Update planned deployment to running command: circleci run release update --status=running - run: name: Validate deployment command: - 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 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. ```yml jobs: deploy-my-service: executor: some-executor steps: ... (existing deployment commands) ... - run: circleci run release log --target-version= ``` 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: ```yml jobs: deploy-my-service: executor: some-executor steps: ... (existing deployment commands) ... - run: name: Log release command: | circleci run release log \ --environment-name= \ --component-name= \ --target-version= ``` * 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 matches the name of the version being deployed. Some examples are provided [above](#examples-for-target-version). * (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 1. In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage. 2. Select **Deploys** in the sidebar. 3. Select the **Environments** tab. 4. Select **Create Environment Integration**. 5. Enter a name for your environment, and a description if you would like. 6. Use the dropdown menu to choose your environment integration type. Choose the 'Custom' option to follow along with this guide. Choose 'Kubernetes Cluster' if you deploy to a Kubernetes cluster and want to use the CircleCI release agent. See the [Set up the CircleCI Release Agent](https://circleci.com/docs/guides/deploy/set-up-the-circleci-release-agent/) page. 7. 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](https://circleci.com/docs/guides/deploy/set-up-rollbacks/). * [Set up Deploys](https://circleci.com/docs/guides/deploy/set-up-deploys/). * [Set up Smart Deployments](https://circleci.com/docs/guides/deploy/set-up-smart-deployments/) to add release validation and automatic rollback.