Circle CI入門 ver2.0ドキュメント

経緯

Circle CIに入門するために、公式ドキュメントを訳してみた。2.0は去年から使えるようになった最新バージョンでDockerイメージが使用可能になったり、ワークフローの機能が使えるようになったりとなかなか使えるようになったらしい。プライベートリポジトリでもビルド実行するの無料だし、設定ファイルも簡単だからぜひ使ってみてください！訳は誤訳あるかもしれません。すいません。以下ドキュメント訳です。

ドキュメント

2.0 Docs

ようこそ、 Circle CI 2.0のドキュメンテーションへ。ここにはCircle CI、ver2.0へのチュートリアル、サンプルやリファレンスドキュメントがあり、以下の二つのセクションに分かれている。

• デベロッパーズ：ホストされたCircle CIアプリケーションを用いたビルド、テスト、デプロイメント自動化のための Circle CI YMLファイルの設定のための説明。
• サーバー管理者：ローカルサーバやプライベートクラウド上にCircle CI をインストールすること、サーバ上で管理するための説明。

このページは最初のグリーンビルドを実行する方法について述べる。

最初のビルドを実行するための必要条件

• いくらかの基本的なGitに関する知識とGithubアカウントが存在するか新しくGitHubアカウントを作成すること。今回は新しいGitHubリポジトリを使うが、Circle CIはBitbucketを使うこともサポートしている。
• いくらかの基本的なターミナルやbashに関する知識とコマンドラインを使っていた経験は役に立つ。

リポジトリを作成すること

1. GitHub上のアカウントを操作する

   • リポジトリタブへ行き、新しく作るか以下のリンクに行く。https://github.com/new.

2. READMEと共にリポジトリを初期化することを選び、リポジトリ作成ボタンをクリックする。

.ymlファイルを追加する。

Circle CIはどのようテスト環境をあなたがセットアップしたいかや、あなたが実行したいテストは何かを識別するYAMLファイルを使用する。Circle CI 2.0では、このファイルはconfig.ymlと呼ばれなくてはならず、.circleciと呼ばれる隠しフォルダの中になくてはならない。MacやLinux、Windowsシステム上で、名前がピリオドから始まるファイルやフォルダはデフォルトでユーザから隠されている、システムファイルとして扱われていた。

1. GitHub上でファイルとフォルダを作成するために、ファイルの新規作成ボタンをリポジトリページでクリックし、.circleci/config.ymlと打ち込む。あなたは今、目の前に空白の.circleciフォルダの中のconfig.ymlがあるだろう。

2. シンプルなcinfig.ymlからはじめるために、以下のテキストをコピーし、GitHubの作成中のファイルウィンドウの中に入れる。

.circleci/config.yml

version: 2
jobs:
  build:
    docker: # See https://docs.docker.com/get-started/#docker-concepts if you are new to Docker.
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A first hello"

1. コメントを入力し、新規ファイルコミットボタンをクリックすることによってファイルをコミットする。

- image: circleci/ruby:2.4.1のテキストの部分はCircle CIに自分のプロジェクトをビルドする時にはどのDockerイメージを使うのかを伝えている。Circle CIはイメージを使ってコンテナを起動する。コンテナとはあなたのプロジェクトを実行するときに必要な言語、システムユーティリティーズ、依存ライブラリ、ウェブブラウザやツールがインストールされる仮想コンピューティング環境である。

あなたのビルドをCircle CI上でセットアップすること

1. このステップのために、あなたはCircle CIアカウントが必要である。Circle CIのサインアップページに訪れ、”Start with GitHub”をクリックする。あなたはGitHubアカウントにビルドを実行するためのCircle CIのアクセス権を与えなくてはならない。もし、あなたがすでにCircle CIアカウントを持っているならば、以下のリンクからダッシュボードに飛ぶことができる。ダッシュボード

2. 次にあなたはCircle CI上にすでに構築されているアクセス可能なプロジェクトをフォローするオプションが与えらる。（これは一般的に企業やオーガニゼーションGithubアカウントに接続している開発者に適用される。）次の画面では、あなたが新しいプロジェクトとして作ったリポジトリをCircle CI上で追加することが可能になるだろう。

3. 新しいリポジトリを追加するために、画面左上のドロップダウンにあなたのGithubアカウント選択されていること確かめ、先ほど作ったリポジトリを探し、Setup projectボタンをクリックする。

4. 次の画面では、あなたはCircle CI上でのあなたのプロジェクトの構成のための選択肢が与えられる。今のところは全てそのままにして、ページ右側の少し下の部分のStart Buildボタンをクリックする。

最初のCircle CIビルドを実行すること

ビルドの開始が自動的に表示されるはずだ。 そして合格するはずだ！何が起こったのか？実行の次のパートを調査するために、CircleCIダッシュボード上の緑のSuccessボタンをクリックする。

1. 環境を起動させる：Circle CIは仮想コンピューティング環境を起動するために' circleci/ruby:2.4.1'のDockerイメージを使った。
2. コードをチェックアウトする：CircleCIはあなたのGitHubリポジトリをチェックアウトし、それをステップ1で起動した仮想環境にcloneした。
3. echo:これはたった一つのconfig.ymlファイル上で書かれた命令だ。Circle CIは"A first hello"を引数にechoコマンドを実行した。
   

たとえ現実的なソースコードがあなたのリポジトリに無くても、config.ymlファイル上に現実的なテストの構成がされていなくても、Circle CIは全てのコマンドが完全にうまくいったのであなたのビルドは”成功した”と考える。多くのプロジェクトはこれより遥かに複雑で、多くの場合、複数のDockerイメージと多数のテストを含む複数のステップがある。あなたはconfig.ymlファイルに書かれるかもしれない、全ての可能なステップについてConfiguration Referenceでより学ぶことができる。

ビルドを壊すこと

config.ymlファイルをGitHubエディター上で編集し、notacommandでecho A hello firstを置き換える。GitHubエディターでCommit Changeボタンをクリックする。あなたがCircle CIのビルドページに戻るとき、新しいビルドが実行されていることを見るだろう。このビルドは赤のFailedボタンと共に失敗し、失敗を知らせるeメールをあなたに送るだろう。

ワークフロー機能を使うこと

ワークフローの動作を見るために、.circleci.config.ymlファイルを編集する。あなたがブラウザウィンドウで編集モードでファイルを開いた後、ファイル内のビルド以降のテキストを選択して、そのセクションを複製するためのテキストをコピーアンドペーストする。それは以下のコードブロックに似ているはずだ。

1. 次に、それらを異なる名前に変えるため、二つのジョブの名前を変更する。この例では、'one'と'two'と命名されている。違ったecho構文の中身に変更する。より長く時間がかかるようなビルドを作るために、私たちはシステムsleepコマンドを追加する。

.circleci/configyml

version: 2
jobs:
  build:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A first hello"
  build:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A first hello"     

1. ワークフローセクションをconfig.ymlファイルに追加する。ワークフローセクションはファイル内のどこに位置することも可能である。ファイルの一番最初か一番最後に一般的に見られる。

.circleci/config.yml

version: 2
jobs:
  one:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A first hello"
      - run: sleep 25
  two:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A more familiar hi"
      - run: sleep 15
workflows:
  version: 2
  one_and_two:
    jobs:
      - one
      - two

1. それらの変更をあなたのリポジトリにコミットし、Circle CIのダッシュボードに戻ってくる。
2. ２つのジョブが並列に実行されていることを見るために、あなたのワークフローのリンクをクリックする。

ワークフローについてOrchestraiting Workflowsドキュメンテーションで詳しく読むことができる。

いくつかの変更をワークスペースの機能を使い加えること

それぞれのワークフローはワークフローが進行するにつれてファイルをダウンストリームのジョブに転送するために使用できる関連づいたワークスペースを持っている。ワークスペースを使用してこの実行に固有でダウンストリームジョブに必要なデータを渡すことができる。以下のようにconfig.ymlに変更を加えることを試みる。

.circleci/config.yml

version: 2
jobs:
  one:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A first hello"
      - run: mkdir -p my_workspace
      - run: echo "Trying out workspaces" > my_workspace/echo-output
      - persist_to_workspace:
          # Must be an absolute path, or relative path from working_directory
          root: my_workspace
          # Must be relative path from root
          paths:
            - echo-output      
  two:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run: echo "A more familiar hi"  
      - attach_workspace:
          # Must be absolute path or relative path from working_directory
          at: my_workspace

      - run: |
          if [[ $(cat my_workspace/echo-output) == "Trying out workspaces" ]]; then
            echo "It worked!";
          else
            echo "Nope!"; exit 1
          fi
workflows:
  version: 2
  one_and_two:
    jobs:
      - one
      - two:
          requires:
            - one

ここでワークスペースについてさらに読むことができる。

ビルドにSSHすること

もしあたながターミナルを使うことが快適であれば、SSH権限のオプションでビルドを再実行することによって、問題を修復するためにあなたはCircle Ciジョブに直接SSHすることがこできる。
あなたはGitHubアカウントにSSH keyを追加することが必要になることに注意する。
[https://help.github.com/articles/connecting-to-github-with-ssh/.

](https://help.github.com/articles/connecting-to-github-with-ssh/.

)

ビルドのssh実行可能セクションからssh文字列をコピーする。ターミナルを開きssh文字列をペーストする。
以下のコマンドを使用し、ワークスペースを使用して作成したファイルの内容を検索して表示できるかどうかを確認する。

参考文献

引用
2.0　Docs -Circle CI-
https://circleci.com/docs/2.0/