はじめてのビルドの成功（グリーンビルド）

CircleCI ではじめてビルドを成功（グリーンビルド）させるためのステップについて詳しくご説明します。

リポジトリを作成する
CircleCI をセットアップする
最初のパイプラインを掘り下げる
チームメイトと協力する

初回のビルド実行にあたっての前提条件

Git の基礎知識
ログイン済みの GitHub または Bitbucket アカウント。このガイドでは GitHub を使用しますが、必要に応じて同じプロセスを Bitbucket で実行してもかまいません。
CircleCI のアカウント
ターミナルまたは bash に関する基本知識と、コマンドラインの使用経験があると役立ちます。

リポジトリを作成する

最初に、GitHub でリポジトリを新規作成します。既存のリポジトリを使用する場合は、このセクションをスキップしても問題ありません。

GitHub に移動して、新規リポジトリを作成します。
リポジトリの名前に (ここでは “hello-world”) を入力して、[Initialize this repository with: (リポジトリを初期化し次を実行:)] セクションで [Add a README file (README ファイルを追加)] を選択します最後に、[Create repository (リポジトリを作成)] をクリックします。

リポジトリを作成する

CircleCI をセットアップする

CircleCI アカウントをまだお持ちでない場合は、ユーザー登録ページに移動し、[GitHub でログイン] をクリックしてアカウントを作成します。

CircleCI のプロジェクトページに移動します。
組織の下に新しいリポジトリを作成した場合は、CircleCI へのログイン時にその組織名を選択する必要があります。
プロジェクトページに移動したら、使用するプロジェクト (今回の例では hello-world) を探し、[Set Up Project (プロジェクトのセットアップ)] をクリックします。
次の画面で、ドロップダウンから言語を選択して、プロジェクト向けの推奨ベストプラクティスがあらかじめ記述されている config.yml ファイルを取得します。この例では、空のリポジトリを用意したので、リスト下部にある Hello World 構成サンプルを使用します。

注: 選択した言語に応じて、参考ドキュメントが画面右側のサイドバーに表示されます。
[Commit and Run (コミットして実行)] をクリックします。リポジトリのルートで、circleci-project-setup という名前の新規ブランチに .circleci/config.yml ファイルが作成されます。この設定で問題がなければ、後にメインブランチにマージする、もしくは引き続き変更を行うことができます。

最初のパイプラインを掘り下げる

ここまでの手順を終えると、自動的にパイプラインの実行が開始され、成功するのを確認できます。実行結果を確認します。パイプラインの緑色の [Success (成功)] ボタンをクリックして、実行について以下の部分を確認しましょう。

最初のパイプライン実行の成功

実行されたワークフローを確認する: [Success (成功)] をクリックすると、実行されたジョブの一覧ページに移動します。初めてのビルドであれば、(1 つのワークフロー内で自動的に実行される) 1 つのジョブ だけが実行されています。この例では、welcome/run という名前のジョブだけが実行されました。 [welcome/run] をクリックして、ジョブのステップを調査してみましょう。
環境をスピンアップする: このプロジェクトのデフォルト設定には、Orb が利用されています。 Orb を使用すると、よく使用する構成にすばやくアクセスできます。この例では、ユーザーに単純なあいさつをする “構築済み” ジョブを実行する circleci/welcome-orb@0.4.1 を使用しています。
ステップの結果を表示する: どのジョブも、一連のステップから構成されています。checkout など、一部のステップは、CircleCI で予約されている特別なコマンドです。他のステップは、ユーザーがそれぞれの目的に合わせて指定します。 welcome Orb を使用しているので、カスタムステップは表示されません。カスタムステップは Orb 内で構成されているからです。しかし、問題ありません。 Orb のソースはオンラインで確認できます。

リポジトリに実際のソースコードがなく、config.yml に実際のテストが構成されていなくても、すべてのステップが問題なく完了したため (終了コード 0 が返されたため)、CircleCI はビルドが “成功した” と見なします。実際のプロジェクトは、これよりもはるかに複雑で、複数の Docker イメージと複数のステップを使用し、膨大な数のテストを行います。 config.yml ファイルで使用できるすべてのステップの詳細については、「CircleCI を設定する」を参照してください。

ビルドを意図的に失敗させる

もう少し複雑なことをしてみましょう。 .circleci/config.yml ファイルを編集してみます。ファイルの編集は、GitHub で直接行うことができます。以下の URL のリポジトリ名とユーザー名 ({ } で囲まれたテキスト) を自分のものに置き換えて、ブラウザーに貼り付けます。 Git に慣れている方は、テキストエディターを使用し、変更を Git にプッシュしてもかまいません。

https://github.com/{username}/{repo}/edit/circleci-project-setup/.circleci/config.yml

今回は、Node Orb を使用してみましょう。以下の内容を config.yml に貼り付けます。

version: 2.1
orbs:
  node: circleci/node@1.1
jobs:
  build:
    executor:
      name: node/default
      tag: '10.4'
    steps:
      - checkout
      - node/with-cache:
          steps:
            - run: npm install
      - run: npm run test

次に、GitHub のエディターで変更をコミットし、CircleCI のプロジェクトページに戻ります。新しいパイプラインが実行され失敗することが確認できます。何が起こったのでしょうか。

Node Orb は、一般的な Node タスクを実行します。今回は空のリポジトリで Node スクリプト npm run test を実行したので、構成が失敗したのです。修正するには、リポジトリで Node プロジェクトをセットアップする必要があります。その方法は、別のチュートリアルで説明します。参考として、デモアプリケーションで、さまざまな言語とフレームワークで CircleCI をセットアップする方法をご覧ください。

ワークフロー機能を使用する

CircleCI を使用する際には、必ずしも Orb を使用する必要はありません。次の例では、カスタム設定ファイルの作成方法を説明します。この例でも、CircleCI のワークフロー機能を使用します。

以下のコードブロックと付記されているコメントを読み進めます。面倒だとしても、どのような処理をしているのかを理解しないままコードをコピー & ペーストするのはやめてください。読み終えたら、ワークフローの動作を確認するために、.circleci/config.yml ファイルを編集して以下のテキストをコピー & ペーストします。

version: 2
jobs: # 今回は 2 つのジョブを用意し、ワークフロー機能でジョブの調整を行います
  one: # 1 つ目のジョブ
    docker: # Docker Executor を使用します
      - image: circleci/ruby:2.4.1 # Ruby 2.4.1 を含む Docker イメージを指定します
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    # ステップは、上記の Docker コンテナ内で実行するコマンドのリストです
    steps:
      - checkout # GitHub からコードをプルします
      - run: echo "A first hello" # "A first hello" を stdout に出力します
      - run: sleep 25 # 25 秒間スリープするようにジョブに指示するコマンド
  two: # 2 つ目のジョブ
    docker: # 前述と同様に Docker イメージ内で実行します
      - image: circleci/ruby:2.4.1
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run: echo "A more familiar hi" # 前述のコマンドに類似した echo コマンドを実行します
      - run: sleep 15 # 15 秒間スリープします
# workflows 以下でマッピングを行い、上記で定義した 2 つのジョブを調整します
workflows:
  version: 2
  one_and_two: # ワークフローの名前
    jobs: # 実行するジョブをここにリストします
      - one
      - two

この変更をリポジトリにコミットし、CircleCI パイプラインページに戻ります。 CircleCI パイプラインが実行中であると表示されます。
実行中のパイプラインをクリックし、作成したワークフローを表示します。 2 つのジョブが同時に実行された (または現在実行されている) ことがわかります。

ワークフローの詳細については、こちらのドキュメントを参照してください。

変更を追加してワークスペース機能を使用する

各ワークフローには 1 つのワークスペースが関連付けられ、ワークフローの進行に伴って後続のジョブにファイルを転送するために使用されます。ワークスペースを使用して、後続のジョブに必要な、実行ごとに固有のデータを渡すことができます。 config.yml を以下のように更新してみます。

version: 2
jobs:
  one:
    docker:
      - image: circleci/ruby:2.4.1
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  #  コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run: echo "A first hello"
      - run: mkdir -p my_workspace
      - run: echo "Trying out workspaces" > my_workspace/echo-output
      - persist_to_workspace:
          # 絶対パスまたは working_directory からの相対パスでなければなりません
          root: my_workspace
          # ルートからの相対パスでなければなりません
          paths:
            - echo-output      
  two:
    docker:
      - image: circleci/ruby:2.4.1
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  #  コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - checkout
      - run: echo "A more familiar hi"  
      - attach_workspace:
          # 絶対パスまたは 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 接続する

ターミナルの操作に慣れている場合は、CircleCI に直接 SSH 接続し、SSH 対応のオプション付きでビルドを実行して、ビルドに関する問題のトラブルシューティングを行うことができます。

SSH 公開鍵を GitHub アカウントに登録する必要があることにご注意ください。詳細はこちら。

SSH でのリビルド

ビルドの SSH 有効化セクションから ssh の接続先をコピーします。ターミナルを開き、ssh の接続先を貼り付けます。

以下のコマンドを使用して、ワークスペースで作成したファイルの内容を表示できるかどうかを確認します。

pwd                  #  "print what directory" の略で、ファイル システム内のどこにいるかを確認できます
ls -al               # 現在のディレクトリに含まれるファイルとディレクトリを一覧表示します
cd <directory_name>  # 現在のディレクトリを <directory_name> ディレクトリに変更します
cat <file_name>      # ファイル <file_name> の内容を表示します

チームメイトと協力する

チームメイトやコラボレーターは、簡単にプロジェクトを閲覧したりフォローしたりできます。チームメイトは、コードをまったくコミットしていないとしても、いつでも無料の CircleCI アカウントを作成してパイプラインを閲覧できます。

はじめてのビルドの成功（グリーンビルド）

初回のビルド実行にあたっての前提条件

リポジトリを作成する

CircleCI をセットアップする

最初のパイプラインを掘り下げる

ビルドを意図的に失敗させる

ワークフロー機能を使用する

変更を追加してワークスペース機能を使用する

ビルドに SSH 接続する

チームメイトと協力する

関連項目

CircleCI

継続的インテグレーション

YAML