0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@CircleCIJapan(CircleCI)
in

【CircleCI】config コンパイルに関する3つの破壊的変更（2026年9月21日施行）

0
Last updated at Posted at 2026-06-15

本記事は、CircleCI 公式コミュニティ（Discuss）に投稿された breaking change のお知らせを日本語に翻訳・整理したものです。コード例は原文のまま掲載し、コード中のコメントのみ日本語化しています。挙動や日付の最終的な根拠は、必ず原文および公式ドキュメントでご確認ください。
原文：Breaking Changes: Config Compilation Updates — September 21, 2026

2026年9月21日、CircleCI は config のコンパイル方法に関する3つの破壊的変更を導入します。これは次世代の config ツールを構築する大きな取り組みの一環であり、より厳格で予測可能なバリデーションによって、将来的により柔軟な config をサポートするための信頼できる基盤を整えることを目的としています。

これらの変更のいずれかに該当するパイプラインは、施行日以降コンパイルに失敗します。本記事の各セクションで、何が変わるのか・影響を受けるかどうかの確認方法・解決方法を確認できます。

なお、この変更は当初それぞれ別々の施行日で個別に案内されていましたが、その後3つの個別投稿が1つに統合され、日付が調整されました。統合後も施行日はさらに2度変更されており、現時点（本記事更新時点）で3つの変更はすべて 2026年9月21日に施行されます。今後さらに変更される可能性があるため、公開直前には必ず原文の最新版を確認してください。

1. 宣言されていないパラメータはコンパイルに失敗します

背景

パイプラインパラメータは、宣言された config ファイル内でのみ解決できます。現在、参照先のパラメータが宣言されていない、またはスコープ外であるという限定的なケースにおいて、config がそのままコンパイルされ、参照が失敗する代わりに暗黙的に null として解決されてしまうことがあります。これは意図しない、トラブルシューティングが困難な挙動につながる可能性があります。

よくある例

次の例では、orb はパイプラインパラメータを使用できないため、この config は不正です。

version: 2.1
parameters:
  bug:
    type: string
    default: "this is buggy"
orbs:
  buggy-orb:
    jobs:
      exhibit-bug:
        docker: [image: "python:2.7"]
        parameters:
          bug:
            type: string
            default: << pipeline.parameters.bug >>
        environment:
          FOO: << parameters.bug >>
        steps:
          - checkout
workflows:
  build-test-deploy:
    jobs:
      - buggy-orb/exhibit-bug

現在、この config はコンパイルされ、FOO は null として解決されます。変更後は、コンパイルに失敗するようになります。

config の確認方法と修正方法

変更が有効化される前に、現時点で自分の config が影響を受けるかどうかをプレビューできます。

  1. config をバリデーションする（いずれかの方法で）
    • UI: config editor を開き、（右下の）「config next」トグルを有効にします。config が自動的に再バリデーションされます。
    • CLI: 最新の CircleCI CLI をインストールまたは更新し（Installing the CircleCI local CLI を参照）、circleci config validate <path-to-config> --next を実行します。
  2. エラーを確認する — 出力内の undeclared-parameter（未宣言パラメータ）エラーを探します。
  3. 修正する — 現在のスコープで宣言されていないパラメータへの参照を削除するか、使用箇所でパラメータを宣言します。
  4. 再バリデーションする — 同じ UI トグルまたは CLI コマンドで、エラーが解消されたことを確認します。

2. when: matches: pattern: の正規表現エンジン更新

when: matches: pattern: 条件の評価に使用する正規表現エンジンが、config コンパイルのセキュリティと信頼性を向上させるために更新されます。9月21日以降、pattern: フィールドで以下の正規表現機能を使用している config はコンパイルに失敗します。

  • 否定先読み（Negative lookaheads）
  • 否定後読み（Negative lookbehinds）
  • 絶対最大量指定子（Possessive quantifiers）
  • 後方参照（Backreferences）

影響を受けるかどうかの確認方法

.circleci/config.yml（および config に取り込まれる orb のソース）の when: matches: pattern: フィールドを検索してください。いずれかの pattern: の値に以下の機能が含まれている場合は、書き換えが必要です。

否定先読み (?!...)

否定先読みは、現在位置でパターンに一致しないことを表明します。特定のブランチ群を除くすべてのブランチで job を実行する用途で使われるのが一般的です。

変更前（動作しなくなります）:

when:
  matches:
    pattern: "^(?!main).*$"
    value: << pipeline.git.branch >>

これは main 以外のすべてのブランチに一致します。

修正:

branches:
  ignore:
    - main

複数の除外条件を持つ例も同様です。

変更前（動作しなくなります）:

when:
  matches:
    pattern: "^(?!master|staging|release|hotfix).*$"
    value: << pipeline.git.branch >>

修正: branches: ignore: または パイプラインフィルタ式（式は config を特定の VCS プロバイダに結びつけないため推奨）に置き換えます。

branches:
  ignore:
    - master
    - /^staging.*/
    - /^release.*/
    - /^hotfix.*/

さらに複雑な、複数の除外を含む例です。

変更前（動作しなくなります）:

^(?!develop$)(?!build_all$)(?!integration-....?)(?!integration2)(?!fedint-us1$)(?!hotfix/.*?/.*$).*

修正:

branches:
  ignore:
    - develop
    - build_all
    - /^integration-.{4,5}/
    - /^integration2/
    - fedint-us1
    - /^hotfix\/.+\/.+/

否定後読み (?<!...)

否定後読みは、現在位置の直前に特定の部分文字列がないことを表明します。単一の正規表現で等価な置き換えはありませんが、肯定一致と否定除外にロジックを分割できます。

変更前（動作しなくなります）:

when:
  matches:
    pattern: "^@myorg\\/[\\w-]+(?<!-uat)@\\d+\\.\\d+\\.\\d+-rc\\.\\d+$"
    value: << pipeline.git.tag >>

これは @myorg/some-pkg@1.2.3-rc.4 のようなパッケージバージョン文字列に一致しますが、-uat で終わるパッケージは除外します。

修正: and + not に分割します。

when:
  and:
    - matches:
        pattern: "^@myorg\\/[\\w-]+@\\d+\\.\\d+\\.\\d+-rc\\.\\d+$"
        value: << pipeline.git.tag >>
    - not:
        matches:
          pattern: "-uat@"
          value: << pipeline.git.tag >>

あるいはパイプラインのロジックで、後読みを使わずに同じ範囲をカバーする only ルールと ignore ルールに分割します。

絶対最大量指定子 ?+, *+, ++

絶対最大量指定子は貪欲に一致し、バックトラックを行いません。末尾の + を削除して通常の量指定子にするだけで対応できます。実用上のすべての入力で挙動は同一です。

変更前（動作しなくなります）:

when:
  matches:
    pattern: "^staging[0-9]?+$"
    value: << pipeline.git.branch >>

修正:

when:
  matches:
    pattern: "^staging[0-9]?$"
    value: << pipeline.git.branch >>

後方参照 \1, \2 など

後方参照は、番号付きグループで以前にキャプチャされたテキストと同じ文字列に一致させ、単一のパターンで2つの部分文字列が同一であることを強制できます。新しいエンジンは、これを単一のパターンで行うことができません。

変更前（動作しなくなります）:

^release/(v\d+\.\d+\.\d+)/\1$

これは release/v1.2.3/v1.2.3 のように、バージョンが2回現れ、かつ両方が同一であるタグに一致します。

修正 — 正規表現を緩める（タグがリリースツールによって生成される場合に推奨）:

when:
  matches:
    pattern: "^release/v\\d+\\.\\d+\\.\\d+/v\\d+\\.\\d+\\.\\d+$"
    value: << pipeline.git.tag >>

これは2つのバージョン文字列が同一であることを強制しなくなりますが、実際にはタグはツールによって生成されるため、不一致が起きる可能性は低いはずです。あるいは、有効な値の集合が小さく既知である場合は、when: or: ブロックで列挙します。

3. version: 2.0 のサポート終了

9月21日以降、すべてのパイプラインは version: 2.1 を使用する必要があります。CircleCI はこれまで数年間、2つの config バージョンをサポートしてきました。v2（レガシー）と v2.1（現行）です。バージョン 2.1 は、orb、パイプラインパラメータ、再利用可能な command、再利用可能な executor、そして厳格なバリデーションを備えた明確に定義されたスキーマを導入しました。次世代の config ツールを構築するにあたり、サポートする単一の設定フォーマットとして v2.1 に統合します。

移行方法

ステップ 1: config の version キーを更新します。

# 変更前
version: 2.0

# 変更後
version: 2.1

ステップ 2: config をバリデーションします。

circleci config validate <path-to-config.yml>

CLI をインストールしていない場合は、CLI インストールドキュメント を参照してください。アプリ内の config editor も使用でき、自動的にバリデーションを行ってエラーを表示します。

ステップ 3: バリデーションエラーを修正します。バリデーションに失敗した場合、その config は v2 では受け入れられていたものの v2.1 の仕様には含まれないパターンを使用している可能性が高いです。よくある問題を以下に示します。完全な v2.1 スキーマについては configuration reference も参照してください。

以降は、移行時によく遭遇するケースごとの症状・原因・修正です。

HEREDOC 構文 <<

症状: run: ステップで未解決のパイプライン式に関するエラーが出る。

原因: バージョン 2.1 は << をパイプラインパラメータ式として解釈します。シェルスクリプトでヒアドキュメント（例: cat <<EOF）を使用している場合、コンパイラがそれを評価しようとします。

修正: << をバックスラッシュでエスケープします。

# 変更前
- run:
    command: |
      cat <<EOF
      some content
      EOF

# 変更後
- run:
    command: |
      cat \<<EOF
      some content
      EOF

job 名に使用できない文字

症状: 不正な job 名に関するエラーが出る。

原因: バージョン 2.1 では、job 名に使用できるのは英字・数字・スペース・ハイフン・アンダースコアのみです。コロン・丸括弧・カンマなどの文字は許可されません。

修正: 該当する job をリネームします。

# 変更前
jobs:
  build (linux):
    ...

# 変更後
jobs:
  build-linux:
    ...

job 定義上の未認識キー

症状: job 上の予期しないキーに関するエラーが出る。

原因: バージョン 2.1 はより厳格なスキーマを持ち、job configuration reference に含まれないキーを拒否します。

修正: job 定義から、configuration reference に記載されていないキーを削除します。config を読み取る外部ツールがそのカスタムキーを使用していた場合は、そのデータを環境変数や別ファイルへ移すことを検討してください。

job 定義上の branches:

症状: branches が job の有効なキーではないというエラーが出る。

原因: job レベルのブランチフィルタリングは、v2.1 で workflow レベルのフィルタに置き換えられました。

修正: ブランチフィルタリングを workflow の設定へ移動します。

# 変更前（v2）
jobs:
  deploy:
    branches:
      only:
        - main

# 変更後（v2.1）
workflows:
  build-and-deploy:
    jobs:
      - deploy:
          filters: pipeline.git.branch == "main"

Docker イメージ定義上のサポート外キー

症状: Docker イメージ定義上の予期しないキーに関するエラーが出る。

原因: バージョン 2.1 は Docker イメージエントリに対してより厳格なスキーマを持ち、仕様に含まれないキーを拒否します。セカンダリコンテナに余分なキーが含まれている場合は削除が必要です。

修正: Docker イメージ定義からサポート外のキーを削除します。サポートされるキーの一覧は Docker executor reference を参照してください。

# 変更前
jobs:
  build:
    docker:
      - image: cimg/node:20.0
      - image: postgres:15
        environment:
          POSTGRES_DB: mydb
        ports:
          - "5432:5432"

# 変更後
jobs:
  build:
    docker:
      - image: cimg/node:20.0
      - image: postgres:15
        environment:
          POSTGRES_DB: mydb

working-directory と working_directory

症状: job が誤ったディレクトリで実行される、または未知のキーに関するエラーが出る。

原因: 正しいキーは working_directory（アンダースコア）です。ケバブケースの working-directory は v2 では暗黙的に無視されており、実際には一度も適用されていませんでした。

修正: working_directory（アンダースコア）を使用します。

machine: executor 内の resource_class

症状: resource_class の配置場所が誤っているというエラーが出る。

原因: v2.1 では、resource_class は machine: ブロック内にネストするのではなく、job のトップレベルキーである必要があります。

修正:

# 変更前
jobs:
  build:
    machine:
      image: ubuntu-2404:current
      resource_class: large

# 変更後
jobs:
  build:
    machine:
      image: ubuntu-2404:current
    resource_class: large

job 上の name: キー

症状: name が job の有効なキーではないというエラーが出る。

原因: name: キーは v2.1 では job 定義上で直接サポートされていません。

修正: job 定義から name: キーを削除します。job に表示名を付けるには、代わりに workflow のエントリで設定します。

workflows:
  build:
    jobs:
      - my-job:
          name: "My Custom Name"

v2.1 では CIRCLE_COMPARE_URL が利用できません

症状: 環境変数 CIRCLE_COMPARE_URL が空、または未定義になる。

原因: CIRCLE_COMPARE_URL は v2 の config でのみ利用可能で、v2.1 には引き継がれません。

修正: パイプライン値 を使って compare URL を自分で組み立てます。

# 変更前（v2）— CIRCLE_COMPARE_URL は自動的に利用可能でした
- run: echo $CIRCLE_COMPARE_URL

# 変更後（v2.1）— パイプライン値を使って自分で定義します
jobs:
  my-job:
    environment:
      CIRCLE_COMPARE_URL: << pipeline.project.git_url >>/compare/<< pipeline.git.base_revision >>..<<pipeline.git.revision>>
    steps:
      - run: echo $CIRCLE_COMPARE_URL

困ったときは

自分の config が影響を受けるかどうか不明な場合や、特定の修正について助けが必要な場合は、原文スレッドへの返信、またはサポートチケットの起票をご利用ください。

本記事は CircleCI 公式 Discuss 投稿の翻訳です。施行日・仕様の最新情報は必ず原文および公式ドキュメントでご確認ください。

更新履歴

  • 2026-06-15: 初版公開（施行日: 2026年7月17日として記載）
  • 2026-07-07: 施行日を2026年8月17日に修正（公式アナウンスによる延長を反映）。統合検証コマンドへの言及を追記。
  • 2026-07-08: 施行日を2026年9月21日に再修正（公式アナウンスによるさらなる延長を反映）。原文URLのスラッグ変遷
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?