開発チームがデプロイの履歴を確認する際、CI/CD のジョブログを遡って実行時刻と対象バージョンを突き合わせる作業が発生します。プロジェクトが複数ある場合、それぞれの CI ログを横断して人力で記録を集める必要があり、デプロイ記録が散在したまま運用が続きます。
CircleCI Deploy Markers を利用すると、デプロイ実行のたびに「いつ・どのバージョンを・どの環境に」デプロイしたかが Deploys UI に記録されます。
本記事では、稼働中のデプロイジョブに Deploy Markers を追加してデプロイ記録を CircleCI に集約する手順と、2026 年 2 月に追加された Version Comparison on the Deploy Timeline を使ったデプロイ間差分の確認方法を紹介します。
Deploy Markers の仕組み
Deploy Markers は、CircleCI のジョブから Environment CLI の circleci run release コマンドを呼び出すことで、Deploys UI に「マーカー」と呼ばれるデプロイ記録を作成する仕組みです。マーカーは以下の状態を持ち、コマンドで状態遷移を行えます。
| Status | 説明 |
|---|---|
| PENDING |
circleci run release plan で作成された直後の状態 |
| RUNNING | デプロイ実行中 |
| SUCCESS | デプロイ成功 |
| FAILED | デプロイ失敗 |
| CANCELED | デプロイがキャンセルされた |
Deploys UI では、これらのマーカーがコンポーネント単位で時系列に並びます。下図は、production 環境に 2 回のデプロイが SUCCESS で記録された状態です。
Configure deploy markers のドキュメントでは、状態を持たせない「ログのみ」のパターンと、状態遷移を伴うパターンの 2 種類が紹介されています。本記事ではまず「ログのみ」を最小構成として説明し、その後に状態遷移を伴うパターンを推奨構成として紹介します。
前提条件
Deploy Markers を導入するために必要な準備は以下の 3 点です。
circleci run release は Environment CLI のコマンドで、CircleCI のビルド環境内でのみ利用できます。ローカル開発機への CircleCI local CLI のインストールは不要です。
ステータスなしのログだけを残す
「とりあえずデプロイ記録だけを残したい」場合は、circleci run release log コマンドを 1 行追加するだけで導入できます。状態遷移は行われず、デプロイ実行のタイミングが LOGGED 状態で Deploys UI に記録されます。
release log コマンドはデプロイジョブの最後（または任意のタイミング）に配置します。--target-version でデプロイしたバージョンの識別子（コミット SHA、セマンティックバージョン等）を渡します。
deploy-production:
steps:
- run:
name: Log deployment
command: |
circleci run release log \
--environment-name=production \
--component-name=my-app \
--target-version=$CIRCLE_SHA1
--environment-name で指定した環境が CircleCI に存在しない場合は自動的に作成されます。--component-name を指定しない場合は CircleCI プロジェクト名が使われます。
release log には deploy-name 引数は不要です。状態遷移を扱わないため、後から状態を更新する手段を持たないシンプルな記録用コマンドとして使えます。複数の環境やコンポーネントを 1 つのワークフローでデプロイする場合は、--environment-name と --component-name を明示的に指定してください。
デプロイの成功・失敗なども記録する
デプロイの成功・失敗まで Deploys UI に反映させたい場合は、circleci run release plan でマーカーを作成し、circleci run release update で状態を更新するパターンを使います。
このパターンでは、デプロイジョブを以下の順序で構成します。
-
release planでマーカーを PENDING 状態で作成 - アーティファクトをビルド（
npm run build） -
release update --status=RUNNINGでマーカーを RUNNING に更新（ビルド完了・本番反映開始の境界） - 本番へ反映（
npm run deploy） -
release update --status=SUCCESS（when: on_success）でマーカーを SUCCESS に更新 -
release update --status=FAILED（when: on_fail）でマーカーを FAILED に更新
以下は、npm run build でアーティファクトを生成し、npm run deploy で本番へ反映する一般的な Node.js プロジェクトを想定した完全な YAML 例です。Set deploy marker name ステップで DEPLOY_NAME を生成し、後続の各ステップで同じ名前を参照することで、ジョブ全体で一貫したマーカーを操作しています。
version: 2.1
orbs:
node: circleci/node@7.2.1
jobs:
test:
executor:
name: node/default
tag: "22.14"
resource_class: small
steps:
- checkout
- node/install-packages
- run:
name: Typecheck
command: npm run typecheck
- run:
name: Test
command: npm run test
- store_test_results:
path: reports
deploy-production:
executor:
name: node/default
tag: "22.14"
resource_class: small
environment:
DEPLOY_ENVIRONMENT_NAME: production
steps:
- checkout
- node/install-packages
- run:
name: Set deploy marker name
command: |
DEPLOY_COMPONENT_NAME="${DEPLOY_COMPONENT_NAME:-$CIRCLE_PROJECT_REPONAME}"
echo "export DEPLOY_COMPONENT_NAME=\"$DEPLOY_COMPONENT_NAME\"" >> "$BASH_ENV"
echo "export DEPLOY_NAME=\"${DEPLOY_COMPONENT_NAME}-${CIRCLE_WORKFLOW_ID}\"" >> "$BASH_ENV"
- run:
name: Plan deployment (deploy marker)
command: |
circleci run release plan "$DEPLOY_NAME" \
--environment-name="$DEPLOY_ENVIRONMENT_NAME" \
--component-name="$DEPLOY_COMPONENT_NAME" \
--target-version="$CIRCLE_SHA1"
- run:
name: Build
command: npm run build
- run:
name: Update deploy marker to RUNNING
command: circleci run release update "$DEPLOY_NAME" --status=RUNNING
- run:
name: Deploy
command: npm run deploy
- run:
name: Update deploy marker to SUCCESS
command: circleci run release update "$DEPLOY_NAME" --status=SUCCESS
when: on_success
- run:
name: Update deploy marker to FAILED
command: circleci run release update "$DEPLOY_NAME" --status=FAILED
when: on_fail
workflows:
build-deploy:
jobs:
- test
- deploy-production:
requires:
- test
filters:
branches:
only: main
上記の構成では、DEPLOY_NAME を <コンポーネント名>-<ワークフローID> の形式で生成しています。ワークフロー単位で一意になるため、同じプロジェクトを並行デプロイしても識別子が衝突しません。DEPLOY_COMPONENT_NAME は Project の環境変数や Context から上書きできる構造になっており、複数プロジェクトに同じ YAML を横展開する際に Repo 名以外をコンポーネント名にしたい場合にも対応できます。
--target-version には CIRCLE_SHA1（コミット SHA）を渡しています。セマンティックバージョンや独自のリリース番号を使いたい場合は、たとえば "1.0.${CIRCLE_BUILD_NUM}-${CIRCLE_SHA1:0:7}" のように組み立てた値を渡してください。
Update deploy marker to RUNNING ステップは、Build と Deploy の境界に配置しています。これは公式ドキュメントの Full config example における Perform deployment → Update to RUNNING → Validate deployment の構造に対応しており、Build がデプロイ可能なアーティファクトを準備するステップ、Deploy が本番への反映を実行するステップ、その間の RUNNING がアーティファクトはできて本番反映が走っている状態、という意味付けになります。Build が失敗した場合は PENDING のまま FAILED に遷移し、Deploy が失敗した場合は RUNNING から FAILED に遷移します。
circleci run release plan と circleci run release update は同じジョブに配置することが推奨されています。別のジョブに分けると、CircleCI Web UI の「Rerun workflow from failed」が使えなくなり、リランの際に必ず「Rerun workflow from start」を選ぶ必要があります。
Deploys UI での見え方
このジョブが稼働すると、Deploys UI のタイムラインに SUCCESS マーカーが時系列で並びます。各マーカーには、対象バージョン（コミット SHA）、環境名、起動したジョブへのリンクが記録されます。
--environment-name で指定した環境は、Deploys UI の Environments タブに自動的に作成されます。
FAILED 状態のマーカーは、Deploys UI のタイムラインで赤色の警告バナーとともに表示されます。以下は別プロジェクトでの FAILED 表示例です（FAILED 状態の見え方は、本記事の構成でも同様になります）。
キャンセル状態を記録する
ワークフローを手動でキャンセルした場合、deploy-production ジョブは canceled ステータスで停止します。しかし、release update のステップが実行されないため、マーカーは PENDING のままになり、Deploys UI 上で「いつまでも完了しないデプロイ」のように見えます。
これを CANCELED として正しく記録するには、ワークフロー内に別の cancel-deploy ジョブを追加します。このジョブは、requires の status 指定機能を使って「deploy-production が canceled になったときだけ起動する」構成にします。
jobs:
cancel-deploy:
resource_class: small
docker:
- image: cimg/base:current
steps:
- run:
name: Update deploy marker to CANCELED
command: |
DEPLOY_COMPONENT_NAME="${DEPLOY_COMPONENT_NAME:-$CIRCLE_PROJECT_REPONAME}"
DEPLOY_NAME="${DEPLOY_COMPONENT_NAME}-${CIRCLE_WORKFLOW_ID}"
circleci run release update "$DEPLOY_NAME" --status=CANCELED
workflows:
build-deploy:
jobs:
- test
- deploy-production:
requires:
- test
filters:
branches:
only: main
- cancel-deploy:
requires:
- deploy-production:
- canceled
filters:
branches:
only: main
requires の - canceled は、CircleCI の Configuration reference - requires で定義されている status 指定の構文です。success、failed、canceled、unauthorized、not_run、terminal の 6 種類が指定可能で、上流ジョブが指定した状態に到達したときだけ下流ジョブを起動できます。
cancel-deploy ジョブ内では deploy-production で生成した DEPLOY_NAME を再生成しています。$CIRCLE_WORKFLOW_ID はワークフロー全体で共通の値のため、同じ計算式で同じデプロイ名を導出できます。
ターミナル状態（SUCCESS、FAILED、CANCELED）に到達したマーカーは、それ以降の release update を受け付けません。SUCCESS に更新した後に CANCELED に変えようとするとエラーになります。
デプロイ間のバージョン差分を確認する
2026 年 2 月にリリースされた Version Comparison on the Deploy Timeline により、Deploys UI から 2 つのバージョン間のコミット差分を確認できるようになりました。これまでは GitHub に移動して compare ビューを開く必要がありましたが、Deploys タイムラインのモーダル内でコミット一覧と GitHub diff へのリンクが表示されます。
タイムライン上でデプロイマーカーを選択して compare ボタンを押すと、以下のようなモーダルが開きます。
Base と Compare それぞれで環境とバージョンを選択でき、2 つのバージョン間に含まれるコミットがリストアップされます。各コミットの「View on GitHub」リンクから、GitHub 上の該当コミットへ直接ジャンプできます。
AI による差分サマリーを有効化する
Enable AI-powered features で Org 全体の AI 機能を有効化すると、上記の Compare モーダルに「AI Summary」セクションが追加されます。コミット一覧から自動的に主要な変更点を抽出し、Major Changes と Minor Changes に分類したプレーン言語の要約を表示します。
まとめ
Deploy Markers は、既存のデプロイジョブに数行のコマンドを追加するだけで、CircleCI の Deploys UI をデプロイ記録の集約先にできる仕組みです。状態遷移を扱う release plan / release update のパターンを使えば、PENDING から SUCCESS / FAILED / CANCELED までの一連のライフサイクルを CircleCI 上で可視化できます。
2026 年 2 月以降の Version Comparison 機能と AI Summary により、デプロイ間のコミット差分とその要約も Deploys UI 内で完結します。インシデント調査やリリースノート作成の起点として活用できます。
本記事では Deploy Markers のみを扱いましたが、ここを起点として Set up a deploy pipeline によるパイプライン化や、Set up a rollback pipeline によるロールバック自動化へ発展させることもできます。