YAML 設定ファイルの概要

クラウド

Server v4.x

Server v3.x

このページの内容

CircleCI とプロジェクトを接続する上で重要なのは、.circleci ディレクトリで実行される config.yml ファイルです。 CircleCI の設定ファイルは、人間が理解しやすいプログラミング言語用のデータシリアライズ形式である YAML で記述されます。 YAML は、JSON の厳密な上位版なので、JSON でできることはすべて YAML でもできます。 CircleCI YAML 設定ファイルは、大半がキーと値のペアとネストされたキーと値のペアで構成されます。

最もベーシックな設定ファイルには、CircleCI のバージョン、実行環境、実行するジョブを記述する必要があります。

CircleCI のバージョン

.circleci/config.yml ファイルには、まず任意の CircleCI のバージョンを記載します。クラウド版 CircleCI や新しいバージョンのサーバーは、CircleCI 2.1 を使用する必要があります。

# CircleCI configuration file

version: 2.1

実行環境

次に、実行するジョブとそのジョブを実行する実行環境を設定ファイルに記述する必要があります。 CircleCI は下記の実行環境をサポートしています。

Docker
Linux VM (仮想マシン)
macOS
Windows
GPU
Arm

設定ファイルの実行環境によって制限があります。実行環境の概要のページを参照して、各実行環境に関する各種情報をご確認ください。

下記の .circleci/config.yml では、Docker 実行環境をジョブ build に追加します。

Docker実行環境を使用する場合は、イメージ・レジストリ（image registries）から Docker プルを認証することを推奨します。認証されたプルでは、プライベートな Docker イメージにアクセスすることができ、レジストリのプロバイダによっては、より高いレート制限が付与される場合もあります。詳細は、 Docker の認証付きプルの使用を参照して下さい。

# CircleCI configuration file
version: 2.1

jobs:
  build:
    docker:
    # Primary container image where all steps run
     - image: cimg/base:2022.05

Docker または Machine Executor がイメージを使用します。サンプルでは、Ubuntu 環境をスピンアップする Docker CircleCI イメージ を使用しています。 macOS を実行環境として使用した場合は、代わりに マシンイメージ を使用できます。これにより、下記サンプルのように Xcode がプリインストールされた専用の仮想マシンがスピンアップされます。このサンプルのイメージには、Docker と CircleCI のビルドのオペレーションに必要な最低限のツールが含まれています。

# CircleCI configuration file
version: 2.1

jobs:
  build:
    macos:
      xcode: 13.3.0

Developer Hub には、ご利用いただける CircleCI Orb のリストがあります。 Orb は、共有可能な設定パッケージで、ビルドを簡易化するためにご使用いただけます。 Slack Orb のチュートリアルのページを参照し、最も人気の Orb を設定する方法をご確認下さい。実行環境に関するドキュメントを参照するか、CircleCI Developer Hub で CircleCI イメージやマシンイメージおよびその構文をご確認ください。

Developer Hub には、ご利用いただける CircleCI Orb のリストがあります。 Orb は、共有可能な設定パッケージで、ビルドを簡易化するためにご使用いただけます。 Slack Orb のチュートリアルのページを参照し、最も人気の Orb を設定する方法をご確認下さい。

CircleCI ジョブとワークフロー

最後にベーシックな CircleCI 設定ファイルに必要なのは、実際に実行するジョブです。ジョブは、ワークフローを使ってオーケストレーションされます。ワークフローとは、一連のジョブと実行順序を定義するルールです。 Docker 設定ファイルのサンプルを使って、ジョブにステップを追加することができます。ステップとは Docker コンテナ内で実行するコマンドのリストです。

# CircleCI configuration file
version: 2.1

jobs:
  build:
    docker:
     - image: cimg/base:2022.05
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
        - run: echo "Say hello to YAML!"

この非常にベーシックなサンプルでは、1 つのジョブ、build のみを実行しており、つまりバックグラウンドでも 1 つのワークフローのみが実行されています。 2 つ目のジョブが追加された場合、workflows を明示的に定義し、実行順序をオーケストレーションする必要があります。 workflows が追加されると、ジョブを反映する名前にジョブ名が更新される場合があります。 1 つのジョブのみが定義されている場合は、上記の例のように、そのジョブを build という名前にする必要があります。

下記サンプルでは、2 つ目のジョブと実行順序を定義する workflows が記述されています。

# CircleCI configuration file
version: 2.1

jobs:
  # Job one with a unique name
  say_hello:
    docker:
     - image: cimg/base:2022.05
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run: echo "Say hello to YAML!"
  # Job two with a unique name
  say_goodbye:
    docker:
     - image: cimg/base:2022.05
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run: echo "Say goodbye to YAML!"

workflows:
  # Name of workflow
  hello_and_goodbye:
    # List of jobs that will run
    jobs:
      - say_hello
      - say_goodbye

CircleCI のアカウントをお持ちの場合、新しいプロジェクトを作成し、.circleci/config.yaml ファイルにこれらのサンプルを追加できます。 CircleCI Web UI で、ジョブのビルドパイプラインで出力された文字列を確認することができます。

YAML は、インデントについてかなり厳しいです。 YAML checker を使ってご自身の YAML を解析し、有効かどうかを確認できます。

より複雑な設定ファイルのチュートリアルが必要な場合は、設定ファイルのチュートリアルをご覧ください。 CircleCI Web UI で説明するため、チュートリアルを開始するには CircleCI のアカウントの設定が完了している必要があります。また、サンプル設定ファイルでも様々なサンプルをご覧いただけます。

Visual Studio Code の拡張機能

CircleCI では VS Code 拡張機能を作成しました。これにより、構文の検証、ハイライト、自動補完機能による提案をリアルタイムに実行でき、設定ファイルの作成や変更、およびトラブルシューティングにかかる時間を短縮できます。

CircleCI VS Code の拡張機能は、 VS コードマーケットプレースからダウンロードできます。

Screenshot showing the definition available on hover

CircleCI アカウントでこの拡張機能を認証すると、コードエディターから直接 CircleCI パイプラインを確認して管理したり、ワークフローのステータス変更の通知が可能になります。 CircleCI VS Code の拡張機能は、 VS コードマーケットプレースからダウンロードできます。

YAML を楽しむ

下記では、複雑な設定ファイルを作成する際に便利な YAML 構文の楽しい例を紹介します。

複数行の文字列

値の文字列が複数行にわたる場合は、 > 記号を使用します。この記号の後には、任意の数の行を記述できます。これは特に、長いコマンドを記述する場合に便利です。

haiku: >
  Please consider me
  As one who loved poetry
  Oh, and persimmons.

注: 複数行の文字列を記述する場合、引用符は必要ありません。

シーケンス

キーと値はスカラーに限定されません。スカラーをシーケンスにマップすることもできます。

scalar:
  - never
  - gonna
  - give
  - you
  - up

シーケンス内の項目をキーと値のペアで記述することもできます。

simulation:
  - within: "a simulation"
  - without:
      a_glitch: "in the matrix"

注: シーケンス内の項目をキーと値のペアで記述する場合は、正しくインデントするように注意してください。

アンカーとエイリアス

アンカーとエイリアスを使用すると、 DRY (Don’t Repeat Yourself: 繰り返しを避ける) の原則に基づいて .circleci/config.yml を作成することができます。アンカーは & 記号、エイリアスは * 記号で識別されます。

song:
  - &name Al
  - You
  - can
  - call
  - me
  - *name

上記のリストを YAML パーサーで読み取ると、次のようなリテラル出力が得られます。

song:
  - Al
  - You
  - can
  - call
  - me
  - Al

マップのマージ

アンカーとエイリアスはスカラー値に対して機能しますが、マップまたはシーケンスを保存するには、 << を使用してエイリアスを挿入します。

default: &default
  school: hogwarts

harry:
  <<: *default
  house: gryffindor

draco:
  <<: *default
  house: slytherin

複数のマップをマージすることもできます。

name: &harry_name
  first_name: Harry
  last_name: Potter

address: &harry_address
  street: 4, Privet Drive
  district: Little Whinging
  county: Surrey
  country: England

harry_data:
  <<: [*harry_name, *harry_address]

注: YAML リポジトリの問題に記載されているように、マップはマージできますが、シーケンス (配列またはリストとも言う) はマージできません。さらに複雑な例は、こちらの Gist を参照してください。

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site