[備忘録] CircleCI / Ruby(公式doc.の最小構成)について各設定項目の概要と参照先リンク

# はじめに

[Language Guide: Ruby - CircleCI](https://circleci.com/docs/2.0/language-ruby/)にて、設定ファイルの各項目について調べた備忘録メモです。
解釈した範囲で短い説明を試みましたが、全体的として参照先のリンク集に近い形になりました。

## 本投稿の目的
- ``/.circleci/config.yml``の構造の把握
- 類似の調査の効率化準備
- 投稿の経験値

# 本編

各所で下記のリファレンスの該当タグへのリンクを貼っています。
**各設定項目のリファレンス**
　[CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference)

## [/.circleci/config.yml](https://circleci.com/docs/2.0/language-ruby/#sample-configuration)

~~~yml:/.circleci/config.yml
version: 2.1 # Use 2.1 to enable using orbs and other features.

# Declare the orbs that we'll use in our config.
# read more about orbs: https://circleci.com/docs/2.0/using-orbs/
orbs:
  ruby: circleci/ruby@1.0 
  node: circleci/node@2

jobs:
  build: # our first job, named "build"
    docker:
      - image: cimg/ruby:2.7-node # use a tailored CircleCI docker image.
    steps:
      - checkout # pull down our git code.
      - ruby/install-deps # use the ruby orb to install dependencies
      # use the node orb to install our packages
      # specifying that we use `yarn` and to cache dependencies with `yarn.lock`
      # learn more: https://circleci.com/docs/2.0/caching/
      - node/install-packages: 
          pkg-manager: yarn
          cache-key: "yarn.lock"
          
  test:  # our next job, called "test"
    # we run "parallel job containers" to enable speeding up our tests;
    # this splits our tests across multiple containers.
    parallelism: 3 
    # here we set TWO docker images.
    docker:
      - image: cimg/ruby:2.7-node # this is our primary docker image, where step commands run.
      - image: circleci/postgres:9.5-alpine 
        environment: # add POSTGRES environment variables.
          POSTGRES_USER: circleci-demo-ruby
          POSTGRES_DB: rails_blog_test
          POSTGRES_PASSWORD: ""
    # environment variables specific to Ruby/Rails, applied to the primary container.
    environment:
      BUNDLE_JOBS: "3"
      BUNDLE_RETRY: "3"
      PGHOST: 127.0.0.1
      PGUSER: circleci-demo-ruby
      PGPASSWORD: ""
      RAILS_ENV: test
    # A series of steps to run, some are similar to those in "build".
    steps:
      - checkout 
      - ruby/install-deps 
      - node/install-packages:
          pkg-manager: yarn
          cache-key: "yarn.lock"
      # Here we make sure that the secondary container boots 
      # up before we run operations on the database.
      - run:
          name: Wait for DB
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
      - run:
          name: Database setup
          command: bundle exec rails db:schema:load --trace
      # Run rspec in parallel
      - ruby/rspec-test

# We use workflows to orchestrate the jobs that we declared above.
workflows:
  version: 2
  build_and_test:     # The name of our workflow is "build_and_test"
    jobs:             # The list of jobs we run as part of this workflow.
      - build         # Run build first.
      - test:         # Then run test,
          requires:   # Test requires that build passes for it to run.
            - build   # Finally, run the build job.
~~~

各設定項目の概要について
　[Orbs、ジョブ、ステップ、ワークフロー - CircleCI](https://circleci.com/docs/ja/2.0/jobs-steps/)

### version:

~~~yml
version: 2.1 # Use 2.1 to enable using orbs and other features.
~~~

[version - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#version)
　CircleCIのバージョンを指定します。


### orbs:

~~~yml
orbs:
  ruby: circleci/ruby@1.0 
  node: circleci/node@2
~~~

**Orbについてのドキュメント**
　[Orbs とは - CircleCI](https://circleci.com/docs/ja/2.0/orb-intro/#section=configuration)
　[Orbs を使う - CircleCI](https://circleci.com/docs/ja/2.0/using-orbs/)
　[orbs - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#orbsversion21-%E3%81%8C%E5%BF%85%E9%A0%88)

Orbとは、ジョブやコマンドなどの設定要素をまとめた共有可能なパッケージのことです。
この設定項目では、[CircleCI Orb Registry](https://circleci.com/orbs/registry/)にあるOrbsからインポートするものを記載します。

**今回使用するOrbのレジストリページ**
　Ruby : [CircleCI Orb Registry - circleci/ruby](https://circleci.com/orbs/registry/orb/circleci/ruby?version=1.0.0)
　Node : [CircleCI Orb Registry - circleci/node](https://circleci.com/orbs/registry/orb/circleci/node?version=2.0.0)

( Orbレジストリのドキュメントにある``Orb Source``は、あくまでドキュメントページを生成するためのソースコードです。
(ファイル階層も含めた)Orb自体のソース情報を確認する場合はGitHubのリポジトリを参照する必要があります。 )

### jobs:

[jobs - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#jobs)
　今回におけるjobsは、2つのパラレルジョブ、buildとtestから構成されます。

#### build:

~~~yml
  build: # our first job, named "build"
    docker:
      - image: cimg/ruby:2.7-node # use a tailored CircleCI docker image.
    steps:
      - checkout # pull down our git code.
      - ruby/install-deps # use the ruby orb to install dependencies
      # use the node orb to install our packages
      # specifying that we use `yarn` and to cache dependencies with `yarn.lock`
      # learn more: https://circleci.com/docs/2.0/caching/
      - node/install-packages: 
          pkg-manager: yarn
          cache-key: "yarn.lock"
~~~

##### docker:

~~~yml
    docker:
      - image: cimg/ruby:2.7-node # use a tailored CircleCI docker image.
~~~

[docker - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#docker)
　Dockerのイメージや、エントリーポイント、コマンドなどを設定します。
　docker-composeの設定項目と似ています。


##### steps:

~~~yml
    steps:
      - checkout # pull down our git code.
      - ruby/install-deps # use the ruby orb to install dependencies
      # use the node orb to install our packages
      # specifying that we use `yarn` and to cache dependencies with `yarn.lock`
      # learn more: https://circleci.com/docs/2.0/caching/
      - node/install-packages: 
          pkg-manager: yarn
          cache-key: "yarn.lock"
~~~

[steps - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#steps)

###### checkout
[checkout - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#checkout)
　チェックアウトディレクトリを指定します。
　デフォルトでは``working_directory``

裏ではBourne shellのスクリプトが実行されてGitHubのソースコードをチェックアウトしているようです。
SSH周りの勉強にもなりそうなので、また機会を改めて調べてみます。

###### ruby/install-deps
[Orb - circleci/ruby](https://circleci.com/orbs/registry/orb/circleci/ruby?version=1.0.0)で定義されるコマンドです。

> description: Install gems with Bundler.
> (引用：ソースから)

Bundlerを使用してGemをインストールします。

#### test:

~~~yml
  test:  # our next job, called "test"
    # we run "parallel job containers" to enable speeding up our tests;
    # this splits our tests across multiple containers.
    parallelism: 3 
    # here we set TWO docker images.
    docker:
      - image: cimg/ruby:2.7-node # this is our primary docker image, where step commands run.
      - image: circleci/postgres:9.5-alpine 
        environment: # add POSTGRES environment variables.
          POSTGRES_USER: circleci-demo-ruby
          POSTGRES_DB: rails_blog_test
          POSTGRES_PASSWORD: ""
    # environment variables specific to Ruby/Rails, applied to the primary container.
    environment:
      BUNDLE_JOBS: "3"
      BUNDLE_RETRY: "3"
      PGHOST: 127.0.0.1
      PGUSER: circleci-demo-ruby
      PGPASSWORD: ""
      RAILS_ENV: test
    # A series of steps to run, some are similar to those in "build".
    steps:
      - checkout 
      - ruby/install-deps 
      - node/install-packages:
          pkg-manager: yarn
          cache-key: "yarn.lock"
      # Here we make sure that the secondary container boots 
      # up before we run operations on the database.
      - run:
          name: Wait for DB
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
      - run:
          name: Database setup
          command: bundle exec rails db:schema:load --trace
      # Run rspec in parallel
      - ruby/rspec-test
~~~

##### parallelism:

~~~yml
parallelism: 3
~~~

[parallelism - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#parallelism)
　ジョブのステップを並列処理するための設定です。

CircleCIには、プロジェクトのテストに掛かる時間を短縮するために、テストを複数のマシンに分散して並列に実行するための仕組みがあり、``parallelism``のキーに並列マシンの個数を指定します。
　パラレルジョブについて：[テストの並列実行 - CircleCI](https://circleci.com/docs/ja/2.0/parallelism-faster-jobs/)

##### docker:

~~~yml
    docker:
      - image: cimg/ruby:2.7-node # this is our primary docker image, where step commands run.
      - image: circleci/postgres:9.5-alpine 
        environment: # add POSTGRES environment variables.
          POSTGRES_USER: circleci-demo-ruby
          POSTGRES_DB: rails_blog_test
          POSTGRES_PASSWORD: ""
~~~

テスト環境を構築します。

##### environment:
~~~yml
    environment:
      BUNDLE_JOBS: "3"
      BUNDLE_RETRY: "3"
      PGHOST: 127.0.0.1
      PGUSER: circleci-demo-ruby
      PGPASSWORD: ""
      RAILS_ENV: test
~~~
[environment - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#environment)
　Rails + PostgreSQLのための環境変数を設定します。

##### steps:

~~~yml
    # A series of steps to run, some are similar to those in "build".
    steps:
      - checkout 
      - ruby/install-deps 
      - node/install-packages:
          pkg-manager: yarn
          cache-key: "yarn.lock"
      # Here we make sure that the secondary container boots 
      # up before we run operations on the database.
      - run:
          name: Wait for DB
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
      - run:
          name: Database setup
          command: bundle exec rails db:schema:load --trace
      # Run rspec in parallel
      - ruby/rspec-test
~~~

###### run

~~~yml
      - run:
          name: Wait for DB
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
      - run:
          name: Database setup
          command: bundle exec rails db:schema:load --trace
~~~

[run - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#run)
　コマンドラインプログラムを呼び出すための項目です。

``dockerize -wait tcp://localhost:5432 -timeout 1m``
　DBサービスの立ち上がりを待機します。
　　[#Dockerize を使用した依存関係の待機 - データベースの設定 - CircleCI](https://circleci.com/docs/ja/2.0/databases/#dockerize-%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%9F%E4%BE%9D%E5%AD%98%E9%96%A2%E4%BF%82%E3%81%AE%E5%BE%85%E6%A9%9F)
　　dockerizeの公式リポジトリ：[jwilder/dockerize: Utility to simplify running applications in docker containers](https://github.com/jwilder/dockerize)

``bundle exec rails db:schema:load --trace``
　マイグレーションファイルは扱わず、db/schema.rbからデータベースを作成します。
　　[スキーマファイルでデータベースを作成 - Rake - Railsドキュメント](https://railsdoc.com/rake#rake_db_schema_load)
　　[6.1 スキーマファイルの意味について - Active Record マイグレーション - Railsガイド](https://railsguides.jp/active_record_migrations.html#%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E6%84%8F%E5%91%B3%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)

### workflows:

~~~yml
# We use workflows to orchestrate the jobs that we declared above.
workflows:
  version: 2
  build_and_test:     # The name of our workflow is "build_and_test"
    jobs:             # The list of jobs we run as part of this workflow.
      - build         # Run build first.
      - test:         # Then run test,
          requires:   # Test requires that build passes for it to run.
            - build   # Finally, run the build job.
~~~

[workflows - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#workflows)
　ジョブを自動化するための設定です。

**version:**
　[version - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#version-1)

**build_and_test:**
　[workflow_name - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#workflow_name)

**jobs:**
　[jobs - workflow_name - CircleCI を設定する - CircleCI](https://circleci.com/docs/ja/2.0/configuration-reference/#jobs-1)
　　``requires``でジョブの依存関係を明確化し、このジョブが実行されるまでに完了されるべきジョブを指定します。
　　即ち、``build``が実行され完了した後に``test``は実行されます。