2月末にアナウンスがあり，CircleCI 1.0 のサポートが終了することになった．時期は今年の8月末で，それまでにマイグレーションをする必要がある．単純にマイグレーションをするだけではなく，せっかくなら CircleCI 2.0 の新機能も積極的に活用したいと思っていて，最近調査をはじめた．今日は「config-translation API」の話をまとめる．
config-translation API とは？
CircleCI 2.0 では，今まで使ってきた circle.yml の記法が使えなくなり，CircleCI 2.0 の記法を使う必要がある（ディレクトリも .circleci/config.yml に変更になる）．そこで CircleCI から公式に提供されている「config-translation API」を使うと，CircleCI 2.0 の記法に変換できる．ただし，ドキュメントにも書いてある通り，注意点（とポイント）が多くあった．
- マイグレーションガイドとなるコメントが含まれている
- 動作を保証するわけではないので，変換した設定ファイルで動作確認をすること
- CircleCI 2.0 で使える「ワークフロー機能」は含まれないため，使う場合は自分で修正する必要がある
- などなど
よって，スタンスとしては「CircleCI 2.0 の設定ファイルを学ぶために」今回の「config-translation API」を使うと良さそう．
試してみた
API は以下のエンドポイントになっている．今回は GitHub リポジトリを対象にするので :vcs-type は github になる．
/project/:vcs-type/:username/:project/config-translation
ブラウザからアクセスすることもできるけど，今回は curl で API を叩くことにした．その場合は，事前に CIRCLE_TOKEN の取得が必要になる．Personal API Tokens の画面 ( https://circleci.com/account/api ) から，API を新規発行しておく．
あとは API を叩くだけで，変換した結果が返ってくる．
$ CIRCLE_TOKEN=xxxxx $ curl https://circleci.com/api/v1.1/project/github/kakakakakku/dotfiles/config-translation?circle-token=${CIRCLE_TOKEN}
学んだこと
変換した結果を抜粋しながら，CircleCI 2.0 の設定ファイルで学んだことをまとめておこうと思う．
Docker イメージを指定できるようになった
version: 2 jobs: build: （中略） # In CircleCI 1.0 we used a pre-configured image with a large number of languages and other packages. # In CircleCI 2.0 you can now specify your own image, or use one of our pre-configured images. # The following configuration line tells CircleCI to use the specified docker image as the runtime environment for you job. # We have selected a pre-built image that mirrors the build environment we use on # the 1.0 platform, but we recommend you choose an image more tailored to the needs # of each job. For more information on choosing an image (or alternatively using a # VM instead of a container) see https://circleci.com/docs/2.0/executor-types/ # To see the list of pre-built images that CircleCI provides for most common languages see # https://circleci.com/docs/2.0/circleci-images/ docker: - image: circleci/build-image:ubuntu-14.04-XXL-upstart-1189-5614f37 command: /sbin/init
CircleCI 2.0 では，任意の Docker イメージを指定して CI を実行できるようになっている．CircleCI 1.0 では，2種類の VM (Ubuntu 12.04 (Precise) or Ubuntu 14.04 (Trusty)) から選ぶ仕組みになっていたため，VM に必要なツールなどをインストールする必要があったけど，構築済の Docker イメージを指定すれば，そのあたりを考慮する必要がなくなり，シンプルになる．ビルド時間の高速化もメリットだと思う．なお，以下のように Pre-Built CircleCI Docker Images も提供されているので，基本的には Docker を使うのがベストプラクティスになりそう．
ちなみに CircleCI 1.0 と同じく VM を使うこともできて，その場合は machine: true と書く．ただし，CiecleCI 2.0 だとあまり使う場面はなさそう．
jobs: build: machine: true
checkout するディレクトリを変更できる
version: 2 jobs: build: working_directory: ~/xxx/yyy （中略） # The following `checkout` command checks out your code to your working directory. In 1.0 we did this implicitly. In 2.0 you can choose where in the course of a job your code should be checked out. - checkout
CircleCI 1.0 だと，自動的にブランチが展開されていたけど，CircleCI 2.0 では意図的に checkout を含める必要がある．また working_directory の設定を変更することで，任意のディレクトリに変更することもできる．
コマンドは全て記載する
CircleCI 1.0 だと，例えばリポジトリに composer.json があれば，自動的に composer install が実行されていたけど，CircleCI 2.0 では自動実行の仕組みがなくなり，全て記載する必要がある．よって CircleCI 2.0 では，以下のように run: を使って composer install を実行する必要がある．
version: 2 jobs: build: working_directory: ~/xxx/yyy （中略） # The following line was run implicitly in your 1.0 builds based on what CircleCI inferred about the structure of your project. In 2.0 you need to be explicit about which commands should be run. In some cases you can discard inferred commands if they are not relevant to your project. - run: composer install --no-interaction
マイグレーションガイド
今回紹介した「config-translation API」を使わなくても，公式のマイグレーションガイドを使って書き換えていくこともできる．ただし，実際に設定を書いてみないとわからないことも多いので，結局はトライアンドエラーになる気がする．
まとめ
- CircleCI 1.0 は今年の8月末でサポートが終了する
- CircleCI 1.0 と CircleCI 2.0 の設定ファイルには互換性がなく，マイグレーションをする必要がある
- 設定ファイルを変換する「config-translation API」が提供されている
- 注意点が多いため「CircleCI 2.0 の設定ファイルを学ぶために」使うと良さそう
- マイグレーションガイド（コメント）は非常に役に立った
