ドキュメント
無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

コンセプト

1+ year ago5 min read
クラウド
Server v4.x
Server v3.x
このページの内容

このガイドでは、CircleCI がお客様の CI/CD パイプラインを管理する方法の基本概念について説明します。

同時実行

CircleCI では、同時実行とは複数のコンテナを使用して、複数のビルドを同時に実行することを指します。 CircleCI のすべてのお客様がシステムを安定した状態で利用できるよう、 リソースクラスごとに同時実行数のソフト制限が設けられています。 ジョブがキュー入る場合は、この制限に達している可能性が考えられます。 年間プランのお客様は、追加料金なくこの制限の拡大を依頼することができます。

設定ファイルのサンプルに示す方法で並列実行を設定するには ワークフローのオーケストレーションを参照してください。

設定

CircleCI では Configuration as Code の理念を掲げています。 CI/CD プロセス全体が config.yml という 1 つのファイルを通じてオーケストレーションされます。 この config.yml ファイルは、プロジェクトの最上部にある .circleci というフォルダーに置かれます。 CircleCI の設定には YAML 構文が使われます。 詳しくは「 YAML の記述」をご確認ください。

├── .circleci
│   ├── config.yml
├── README
└── all-other-project-files-and-folders

.circleci/config.yml は、プロジェクトの全パイプラインを定義する強力な YAML ファイルです。 使用される様々なキーの概要については、 設定ファイルのリファレンスをご覧ください。

CircleCI の設定はお客様のプロジェクトの様々なニーズに合わせて変更できます。 下記の用語は粒度と依存度の順に並べられており、最も一般的な CircleCI プロジェクトのコンポーネントを表しています。

  • パイプライン: 設定全体を表します (Server v2.x では利用できません)。
  • ワークフロー: 複数の ジョブ のオーケストレーションを行います。
  • ジョブ: コマンドを実行する一連の ステップ を実行します。
  • ステップ: 依存関係のインストールやテストの実行などのコマンドやプロジェクトに必要な作業のシェルスクリプトを実行します。

下記では、

Java アプリケーション例を用いてさまざまな設定要素を紹介します。

設定要素

コンテキスト

コンテキストは、環境変数を保護し、プロジェクト間で共有するためのメカニズムを提供します。 環境変数は、名前と値のペアとして定義され、実行時に挿入されます。 コンテキストを作成したら、config.yml ファイルのワークフローセクションで context キーを使って、任意のジョブに当該コンテキストに関連付けられた環境変数へのアクセス権を付与することができます。

詳細は、 コンテキストの使用を参照して下さい。

データの永続化

データの永続化により、ジョブ間でデータを動かし、ビルドを高速化することができます。 データを永続化するには、キャッシュ、ワークスペース、アーティファクトを使った 3 つの方法があります。

ワークフローの図

キャッシュ

キャッシュは、依存関係、ソースコードなどを 1つのファイルとして、または複数のファイルが入ったディレクトリとしてオブジェクトストレージに格納します。 ビルドを高速化するために、各ジョブには、以前のジョブからの依存関係をキャッシュするための特別な手順が含まれている場合があります。

キャッシュをクリアする必要がある場合は、 依存関係のキャッシュのページで詳細をご確認ください。

ワークスペース

ワークスペースは、ワークフロー対応のストレージ メカニズムです。 ワークスペースには、ダウンストリームジョブで必要になる可能性がある、ジョブ固有のデータが保存されます。 各ワークフローには、それぞれに一時的なワークスペースが関連付けられています。 ワークスペースは、ジョブの実行中にビルドした固有のデータを、同じワークフローの他のジョブに渡すために使用されます。

アーティファクト

アーティファクトにはワークフローが完了した後もデータが維持され、ビルドプロセス出力の長期ストレージとして使用できます。

アーティファクト、ワークスペース、キャッシュの各機能には下記のような違いがあります。

タイプライフタイム用途例
アーティファクト数か月長期アーティファクトを保存します。Job ページの [Artifacts (アーティファクト)] タブで、tmp/circle-artifacts.<hash>containerなどのディレクトリの下に表示されます。
ワークスペースワークフローの期間attach_workspace: ステップを使用して、ダウンストリーム コンテナにワークスペースをアタッチします。attach_workspace を実行すると、ワークスペースの内容全体がコピーされ、再構築されます。
キャッシュ数か月ジョブ実行の高速化に役立つ非必須データ (npm、Gem パッケージなど) を保存します。追加するディレクトリのリストへの path と、キャッシュを一意に識別する key (ブランチ、ビルド番号、リビジョンなど) を指定した save_cache ジョブ ステップ。 restore_cache と 適切な key を使ってキャッシュを復元する。

ワークスペース、キャッシュ、アーティファクトに関する詳細は、「 Persisting Data in Workflows: When to Use Caching, Artifacts, and Workspaces (ワークフローでデータを保持するには: キャッシュ、アーティファクト、ワークスペース活用のヒント)」を参照してください。

Docker レイヤー キャッシュ

Docker Layer Caching (DLC ) により、 ジョブにおいてビルドされた Docker イメージの個々のレイヤーがキャッシュされます。 変更されていないレイヤーは、毎回イメージを再ビルドするのではなく、後続の実行において使用されます。

下記の config.yml スニペットでは、build_elixir ジョブで ubuntu-2004:202104-01 Dockerfile を使ってイメージをビルドしています。 machine executor キーの下に docker_layer_caching: true を追加することで、この Elixir イメージがビルドされるときに CircleCI が各 Docker イメージレイヤーを確実に保存するようになります。

version: 2.1
jobs:
  build_elixir:
    machine:
      image: ubuntu-2004:202104-01
      docker_layer_caching: true
    steps:
      - checkout
      - run:
          name: build Elixir image
          command: docker build -t circleci/elixir:example .

後続のコミットでは、Dockerfile が変更されていない場合、DLC は ` build Elixir image`のステップでキャッシュから各 Docker イメージレイヤーをプルし、イメージのビルドが著しく高速化します。

詳細は、 Docker レイヤーキャッシュを参照して下さい。

ダイナミックコンフィグ

各プロジェクトの設定を手動で作成する代わりに、特定のパイプラインパラメーターまたはファイルパスに基づいて、この設定を動的に生成することができます。 これは、チームがモノレポ（単一のリポジトリ）で作業している場合に特に役立ちます。 ダイナミックコンフィグを使うと、プロジェクトの特定の部分からビルドをトリガーできます。毎回すべてを再ビルドする必要はありません。

詳細は、 ダイナミックコンフィグを参照して下さい。

実行環境

設定内で定義された個々のジョブは、一意の実行環境で実行されます。 CircleCI ではこれらを Executor と呼んでいます。 Executor は、Docker コンテナまたは Linux、Windows、または macOS を実行する仮想マシンです。

ジョブの図

Executor ごとにイメージを定義することができます。 イメージは、実行コンテナや仮想マシンを作成するための指示を含むパッケージ化されたシステムです。 CircleCI では、 Docker の Executor で使用するさまざまなイメージを提供しています。これを CircleCI イメージ と呼んでいます。 ビルド済み CircleCI Docker イメージの詳細については、 こちらを参照してください。

プライマリコンテナは、 .circleci/config.yml ファイルに最初にリストされているイメージによって定義されます。 ここでコマンドが実行されます。 Docker Executor は、Docker イメージを使用してコンテナを起動します。 Machine Executor は完全な Ubuntu 仮想マシン イメージを起動します。 比較表と考慮事項については、 Executor の概要を参照してください。 さらにイメージを追加して、セカンダリ / サービスコンテナをスピンアップできます。

Docker Executor を使って Docker コマンドを実行する際のセキュリティを強化するために、setup_remote_docker キーを使用して、これらのコマンドを実行する別の Docker コンテナをスピンアップできます。 詳細は、 Docker コマンドの実行ガイドを参照して下さい。

注: macOS は CircleCI Server v 2.x. では使用できません。

イメージ

イメージは、実行コンテナを作成するための指示を含むパッケージ化されたシステムです。 プライマリコンテナは、 .circleci/config.yml ファイルに最初にリストされているイメージによって定義されます。 ここで、Docker または Machine Executor を使用してジョブのコマンドが実行されます。

Docker Executor は、Docker イメージを使用してコンテナをスピンアップします。 CircleCI では一般的なプログラミング言語に対応する CircleCI イメージを Docker Hub 上に用意しています。

Machine Executor は完全な Ubuntu 仮想マシンイメージをスピンアップします。これにより、OS リソースへのフルアクセスやジョブ環境の完全な制御が可能になります。 詳細は、 マシンの使用を参照して下さい。

詳細は、 実行環境の概要のページを参照してください。

 version: 2.1
 jobs:
   build1: # job name
     docker: # Specifies the primary container image,
     # see circleci.com/docs/circleci-images/ for
     # the list of pre-built CircleCI images on dockerhub.
       - image: cimg/base:2022.04-20.04
         auth:
           username: mydockerhub-user
           password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

       - image: postgres:14.2 # Specifies the database image
         auth:
           username: mydockerhub-user
           password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        # for the secondary or service container run in a common
        # network where ports exposed on the primary container are
        # available on localhost.
         environment: # Specifies the POSTGRES_USER authentication
          # environment variable, see circleci.com/docs/env-vars/
          # for instructions about using environment variables.
           POSTGRES_USER: user
...
   build2:
     machine: # Specifies a machine image that uses
     # an Ubuntu version 20.04 image.
     # The image uses the current tag, which always points to the most recent
     # supported release. If stability and determinism are crucial for your CI
     # pipeline, use a release date tag with your image, e.g. ubuntu-2004:202201-02
       image: ubuntu-2004:current
...
   build3:
     macos: # Specifies a macOS virtual machine with Xcode version 12.5.1
       xcode: "12.5.1"
 ...

ジョブ

ジョブは設定の構成要素です。 また、必要に応じてコマンド / スクリプトを実行する ステップの集まりです。 各ジョブでは、docker、machine、windows、macos のいずれかの Executor を宣言する必要があります。 docker の場合、プライマリコンテナで使うには イメージを指定する必要があります。 macos の場合、 Xcode のバージョンを指定する必要があります。 windows の場合、 Windows Orb を指定する必要があります。

ジョブの図

Orb

Orb は、再利用可能なコードスニペットです。Orb を使用すると、繰り返しのプロセスを自動化でき、手早くプロジェクトをセットアップできます。サードパーティ製ツールとの連携も容易になります。 設定ファイルで Orb を使用する方法と Orb 設計の概要については、 Orb のコンセプトを参照してください。 CircleCI Orb レジストリでは、構成作業の簡素化に役立つ Orb を検索できます。

設定セクションの図は、Orb を使用して Java 設定を簡素化する例です。 下記の図では、 Maven Orb を使って簡易化された設定を紹介しています。 ここでは Orb は、Maven でステップを実行し共通のジョブを実行できるデフォルトの Exexcutor を設定しています (maven/test ) 。

ワークフローの図

並列実行

プロジェクトに含まれるテストの数が多いほど、テストを 1 台のマシンで実行するのに時間がかかるようになります。 並列実行 により、指定した数の別々の Executor にテストを分散することができます。

テストスイートは通常、.circleci/config.yml ファイルの ジョブレベルで定義します。 parallelism キーには、ジョブのステップを実行するためにセットアップする独立した Executor の数を指定します。

ジョブのステップを並列に実行するには、parallelism キーに 1 よりも大きい値を設定します。

# ~/.circleci/config.yml
version: 2.1
jobs:
  test:
    docker:
      - image: cimg/<language>:<version TAG>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    parallelism: 4

並列実行

詳細は、 テストの並列実行を参照して下さい。

パイプライン

CircleCI パイプラインとは、プロジェクトで作業をトリガする際に実行する一連のプロセスすべてを指します。 パイプラインには、ジョブを管理するワークフローが含まれます。 これらは全てプロジェクトの 設定ファイルで定義されます。 ハイプラインは CircleCI Server v2.x では使用できません。

パイプラインとは、設定と対話するための手法です。

プロジェクト

CircleCI のプロジェクトは、お客様の バージョンコントロールシステム (VCS) 内の、関連するコードリポジトリの名前を共有します。 CircleCI アプリのサイドバーから Projects を選択し、プロジェクトダッシュボードに入力します。 ここからアクセス可能なプロジェクトの設定やフォローが可能です。

プロジェクトダッシュボードで、以下のいずれかを実行します。

  • VCS で所有者になっているプロジェクトを セットアップ する.
  • 組織内のプロジェクトを フォロー して、パイプラインにアクセスし、プロジェクトのステータスに関する メール通知を受け取る

header

リソースクラス

リソースクラスは、ジョブで利用可能なコンピューティングリソースを制御できる設定オプションです。 ジョブの実行環境を指定すると、 設定ファイルでリソースクラスが定義されて いない場合 、その環境にはデフォルトのリソースクラスの値が設定されます。 デフォルト値にするよりもリソースクラスを指定することをお勧めします。

下記の例では Docker 実行環境でリソースクラスを定義する方法を紹介します。

jobs:
  build:
    docker:
      - image: cimg/node:current
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    resource_class: large

すべての実行環境の例は、下記ページでご確認いただけます。

各種リソースクラスの料金とプランに関する情報は リソースクラス製品のページをご覧ください。

resource_class キーは、 セルフホストランナーインスタンスの設定にも使用されます。

手順

ステップは通常、ジョブを完了するために必要な実行可能コマンドの集まりです。 たとえば以下の例では、 checkout ステップ (すべての CircleCI プロジェクトで使用できるビルトインステップ) が SSH コマンドでジョブのソースコードをチェックアウトします。 次に、run ステップで、デフォルトで非ログインシェルを使用して、make test コマンドなどのカスタムコマンドを実行します。 コマンドは、 ジョブ宣言の外部 に定義することもでき、設定全体で再利用することができます。

#...
jobs:
  build:
    docker:
      - image: <image-name-tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout # Special step to checkout your source code
      - run: # Run step to execute commands, see
      # circleci.com/docs/configuration-reference/#run
          name: Running tests
          command: make test # executable command run in
          # non-login shell with /bin/bash -eo pipefail option
          # by default.
#...

ユーザー種別

ここでは CircleCI プロジェクトに関連するユーザータイプを紹介します。 多くのユーザーは、 VCS アカウントから継承された権限を持っています。

  • 組織の管理者とは、 VCS から継承された権限レベルのことです。
    • GitHub: オーナー であり、CircleCI 上の少なくとも 1 つのプロジェクトビルドをフォローしています。
    • Bitbucket: 管理者であり、CircleCI の少なくとも 1 つのプロジェクトのビルドをフォローしています。

  • プロジェクト管理者とは、GitHub または Bitbucket リポジトリをプロジェクトとして CircleCI に追加するユーザーを指します。

  • ユーザーとは、組織内の個々のユーザーを指します。

  • CircleCI ユーザーとは、ユーザー名とパスワードを使用して CircleCI プラットフォームにログインできる人を指します。 関係する CircleCI プロジェクトを表示したりフォローするには、ユーザーが GitHub または Bitbucket 組織に追加されている必要があります。 ユーザーは、環境変数に保存されているプロジェクト データを表示することはできません。

ワークフロー

ワークフローは、ジョブをオーケストレーションします。 ワークフローは、ジョブのリストとその実行順序を定義します。 ジョブは、同時実行、順次実行、スケジュール実行、あるいは承認ジョブを使用した手動ゲートによる実行が可能です。

下記の設定サンプルでは、build_and_test というワークフローを紹介しています。build1 ジョブを実行し、その後 build2 ジョブと build3 ジョブを同時に実行します。

関連項目

はじめてのビルドの成功（グリーンビルド) では、動作中のパイプラインを設定する方法を順を追って紹介しています。

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