Linux プロジェクトの 1.0 から 2.0 への移行
このドキュメントでは、CircleCI 1.0 を 2.0 に移行する際に最初に行う作業について説明します。移行作業ではまず、既存の 1.0 の設定ファイルをコピーして利用し、古いキーに対応する新しいキーがある場合はキーを置き換えます。
ここで説明する手順だけでは移行プロセスは完了しないこともありますが、このドキュメントの目的は、大部分のキーを同等のネスト構文に置き換えてから新しい機能を追加できるよう支援することです。
circle.yml
ファイルがない場合は、最初から 2.0 config.yml
のサンプル ファイルを参考にしてください。
概要
CircleCI では、.circleci/config.yml
を作成して新しい必須キーを追加し、それらのキーに値を定義する必要があります。 メモ: 並列処理は .circleci/config.yml
ファイルでのみ設定できます。CircleCI アプリケーションでの並列処理設定は無視されます。
既に circle.yml
ファイルがある場合は、以降の各セクションの手順に従って、既存のファイルをコピーし、新しい必須キーを記述し、1.0 のキーを検索して 2.0 のキーに置き換えます。
1.0 から 2.0 への config-translation
エンドポイントを使用する
config-translation
エンドポイントを使用すると、1.0 の設定ファイルから 2.0 の設定ファイルへの変換をすぐに始めることができます。詳細については、「1.0 から 2.0 への config-translation エンドポイントを使用する」を参照してください。
必須キーを構成する手順
-
既存の
circle.yml
ファイルをコピーして、プロジェクト リポジトリのルートにある新しい.circleci
ディレクトリに置きます。 -
.circleci/circle.yml
の名前を.circleci/config.yml
に変更します。 -
.circleci/config.yml
ファイルの先頭に、version: 2
を記述します。 -
config.yml
ファイルのバージョンを指定する行の後に、以下の 2 行を追加します。 既存の構成内容にmachine:
を記述していた場合は、machine:
を以下の 2 行に置き換え、古い設定ファイルのすべてのセクションをbuild
の下にネストします。jobs: build:
-
docker:
キーと- image:
キーを記述するか、machine: true
を設定するか、macos
を指定して、プライマリ コンテナを実行するときの言語とバージョンを追加します。 以下のruby:
の例のように、構成に言語とバージョンが含まれている場合は、修正が必要です。ruby: version: 2.3
上記を以下の 2 行に置き換えます。
docker: - image: circleci/ruby:2.3-jessie
最初に記述したイメージのインスタンスがプライマリ コンテナになります。 ジョブのコマンドはこのコンテナ内で実行されます。ジョブごとにコマンドを宣言します。 Docker コンテナを初めて使用する場合は、「Docker 入門」を参照してください。
machine: true
使用可能な VM イメージの詳細については、「Executor タイプを選択する」の「Machine の使用」を参照してください。
macos: xcode: "9.0"
-
ソース ファイルに対してジョブを実行するには、
checkout:
ステップが必要です。steps:
の下にcheckout:
をネストして各ジョブを記述します。それには、以下のコードを検索します。checkout: post:
上記を以下のように置き換えます。
steps: - checkout - run:
以下に例を示します。
checkout: post: - mkdir -p /tmp/test-data - echo "foo" > /tmp/test-data/foo
上の例は次のようになります。
steps: - checkout - run: mkdir -p /tmp/test-data - run: echo "foo" > /tmp/test-data/foo
checkout
ステップを使わない場合でも、このステップをconfig.yml
ファイルに追加する必要があります。 -
(オプション) ビルドへの SSH 接続を有効化するには、
add_ssh_keys
ステップとフィンガープリントを追加します。詳細については、「CircleCI を設定する」を参照してください。 -
http://codebeautify.org/yaml-validator で YAML をバリデーションして、変更をチェックします。
環境変数
CircleCI 2.0 では、定義されたすべての環境変数はリテラルとして処理されます。 コマンド内で変数を挿入するには、現在のシェルで変数を設定します。
詳細については、「環境変数を使用する」を参照してください。
ワークフローを構成する手順
迅速なフィードバック、再実行時間の短縮、効率的なリソースの使用によって、ソフトウェア開発をスピードアップさせるには、以下の手順に従ってワークフローを構成します。
-
ワークフロー機能を使用するには、ビルド ジョブを複数のジョブに分割し、それぞれに一意の名前を付けます。 デプロイのみが失敗したときにビルド全体を再実行しなくても済むように、最初はデプロイ ジョブのみを分割するだけでもよいでしょう。
-
ベスト プラクティスとしては、
workflows:
、version: 2
、<ワークフロー名>
の各行をマスター.circleci/config.yml
ファイルの末尾に追加します。<ワークフロー名>
は、実際のワークフローの一意の名前に置き換えてください。 メモ:config.yml
ファイルのワークフロー セクションは、構成の中にネストしません。ワークフロー セクションのversion: 2
はconfig.yml
ファイルの先頭にあるversion:
キーとは別に設定するものであるため、ワークフロー セクションはファイルの末尾に置くのが最善です。workflows: version: 2 <ワークフロー名>:
-
<ワークフロー名>
の下にjobs:
キーの行を追加し、オーケストレーションするジョブ名をすべて記述します。 この例では、build
とtest
を並列に実行しています。workflows: version: 2 <ワークフロー名>: jobs: - build - test
-
別のジョブが成功したかどうかに応じて順次実行する必要があるジョブについては、
requires:
キーを追加し、そのジョブを開始するために成功する必要があるジョブをその下にネストします。curl
コマンドを使用してジョブを開始していた場合、ワークフロー セクションでは、そのコマンドを削除してrequires:
キーでジョブを開始できます。- <ジョブ名>: requires: - <ジョブ名>
-
特定のブランチでジョブを実行する必要がある場合は、
filters:
キーを追加し、その下にbranches
とonly
キーをネストします。 ジョブを特定のブランチで実行してはいけない場合は、filters:
キーを追加し、その下にbranches
とignore
キーをネストします。 メモ: ワークフローは、ジョブ セクションに記述してあるブランチ指定を無視します。したがって、ジョブでブランチを指定していて、後からワークフローを追加する場合は、ジョブ セクションのブランチ指定を削除し、config.yml
のワークフロー セクションで以下のようにブランチを宣言する必要があります。- <ジョブ名>: filters: branches: only: master - <ジョブ名>: filters: branches: ignore: master
-
http://codebeautify.org/yaml-validator で再度 YAML をバリデーションして、形式が正しいことをチェックします。
2.0 で非推奨となるキーの検索と置換
- 構成にタイムゾーンが含まれる場合は、
timezone: America/Los_Angeles
を検索して、以下の 2 行に置き換えます。
environment:
TZ: "America/Los_Angeles"
- $PATH を変更している場合は、
.bashrc
ファイルにパスを追加し、以下の部分を
environment:
PATH: "/path/to/foo/bin:$PATH"
次のように置き換えてシェルにロードします ($BASH_ENV ファイルはランダムな名前で既に /tmp に置かれています)。
steps:
- run: echo 'export PATH=/path/to/foo/bin:$PATH' >> $BASH_ENV
- run: some_program_inside_bin
-
hosts:
キーを検索し、たとえば以下のような部分を
hosts:
circlehost: 127.0.0.1
次のように run
ステップに置き換えます。
steps:
- run: echo 127.0.0.1 circlehost | sudo tee -a /etc/hosts
-
dependencies:
、database
、またはtest
とoverride:
の行を検索し、たとえば以下のような部分は
dependencies:
override:
- <インストール済み依存関係>
次のように置き換えます。
- run:
name: <名前>
command: <インストール済み依存関係>
-
cache_directories:
キーを検索し、
cache_directories:
- "vendor/bundle"
次のように置き換えて steps:
の下にネストし、実際のアプリケーションに合わせて適切にカスタマイズします。
- save_cache:
key: dependency-cache
paths:
- vendor/bundle
-
restore_cache:
キーをsteps:
の下にネストして追加します。 -
deployment:
を検索し、次のように置き換えてsteps
の下にネストします。
- deploy:
YAML のバリデーション
.circleci/config.yml
にすべてのセクションを記述したら、http://codebeautify.org/yaml-validator などのツールを使用して、YAML 構文が正しい形式かどうかをチェックすることをお勧めします。 次に、circleci
CLI を使用して、新しい構成が CircleCI 2.0 スキーマに照らして正しいかどうかをバリデーションします。 手順については、「CircleCI のローカル CLI の使用」を参照してください。 すべての問題を修正したら、更新した .circleci/config.yml
ファイルをコミットします。 コミットをプッシュすると、ジョブが自動的に開始され、それを CircleCI アプリケーションでモニタリングできます。
次のステップ
- 「2.0 への移行のヒント」を参照してください。
- デプロイの構成例については、「デプロイの構成」を参照してください。
- CircleCI 2.0 の Docker イメージおよび machine イメージの詳細については、「Executor タイプを選択する」を参照してください。
- CircleCI 2.0 の
jobs
とsteps
の正確な構文と使用可能なすべてのオプションについては、「CircleCI を設定する」を参照してください。