GitLab CI_PIPELINE_IID のリセットは可能？現実的な対応方法

公式には推奨されておらず、

ci_pipeline_iid をリセットする方法も提供されていません。

この値を本当にリセットしたい場合は、

プロジェクトを削除して再作成する必要があります。

そのときに初めて pipeline IID がリセットされます。

ただし、この破壊的な方法を採用するケースは多くありません。

そのため、ユニークな ID が必要なら

自分でルールを作る必要があります。

gitlab-ci.yml の仕組みを使えば、

同等の効果を実現できます。

以下はサンプルコードです。

stages:
  - prepare
  - build

variables:
  COUNTER_FILE: counter.txt

# 準備ステージ：カウンターを読み込む or 初期化
prepare_counter:
  stage: prepare
  script:
    - |
      if [ -f $COUNTER_FILE ]; then
        echo "Found counter file."
        COUNTER=$(cat $COUNTER_FILE)
        COUNTER=$((COUNTER + 1))
      else
        echo "No counter file found, start from 1."
        COUNTER=1
      fi
      echo $COUNTER > $COUNTER_FILE
      echo "PIPELINE_COUNTER=$COUNTER" >> variables.env
  artifacts:
    reports:
      dotenv: variables.env
  cache:
    key: project-counter
    paths:
      - $COUNTER_FILE

# build job では PIPELINE_COUNTER を直接利用可能
build_job:
  stage: build
  dependencies:
    - prepare_counter
  script:
    - echo "This is build number: $PIPELINE_COUNTER"

GitLab CI では、

cache は異なる pipeline/job 間でファイルを共有するために使われます。

cache key を削除・変更しない限り、counter.txt は保持され、後続 pipeline でも使われます。

この例では：

cache:
  key: project-counter
  paths:
    - $COUNTER_FILE

すべての pipeline が同じ cache key（project-counter）を使います。

そのため同一プロジェクト内の pipeline は同じ counter.txt を共有します。

pipeline 実行後、

GitLab Runner は更新済みの counter.txt を cache に保存します。

次の pipeline はそれを再利用します。

注意事項：

1. cache は永続を保証しません。
   • runner / ストレージの状況に応じて、GitLab が古い cache を削除することがあります（特に self-hosted runner のディスククリーン時）。
   • cache が消えた場合、次の pipeline は「counter.txt が見つからない -> 1 から開始」となります。
2. pipeline 同時実行時は race condition が起きる可能性があります。
   • 2 つの pipeline が同時に走ると、同じ古い cache を読み、同じ連番を計算してしまうことがあります。
   • 要件が「必ず一意で重複なし」であれば、外部ストレージ（DB、Git tag、Artifacts API など）を検討してください。

---

参考資料：

1. change CI_PIPELINE_IID manually
2. Add ability to setup CI_PIPELINE_IID value for next pipelines.
3. Using CI_PIPELINE_IID variable, how can I navigate back to the corresponding commit in GitLab CI?