Kekeの日記

エンジニア、読書なんでも

CircleCIでOrbsを公開する

https://techcrunch.com/wp-content/uploads/2018/11/CircleCI-Orb-transparent-animated-GIF.gif

Orbsとは

Orbsとはconfig.ymlに書いてあるJobやワークフローをシェアする機能になっていて、v2.1から追加された機能になっています。

シェアされたものは自身のWorkflowに取り込んで、開発スピードをあげることができます。

正式なOrbsはOrbs Registryにあります。

なんのため?

公式には以下のためだと書かれています。

  • DRYサポートの向上
  • プロジェクト間のコードの再利用のため
  • 一般的な設定へ簡単にアクセスできるようにするため

Orbsの構造

以下の単位で構成されています。

  • version: 2.1: バージョン指定
  • description::Orbsの指定
  • commands: コマンド一覧
  • jobs: ジョブ一覧
  • executors: executorの指定
  • orbs: Orbsの指定

はじめに

Circli CLIを使えるようにする

以下のようにアップデートします。

brew update circleci

まだ、インストールしていない人は

brew install circleci

でインストールすることができます。

また、有効化する必要があるので以下のコマンドを叩きます。

circleci setup

=> 
✔ CircleCI API Token: ****************************************
API token has been set.
✔ CircleCI Host: https://circleci.com
CircleCI host has been set.
Setup complete. Your configuration has been saved.

Orbsを有効化する

GUIで

左のTabBarから「Setting] > 「Security」を選択して有効化します。

f:id:bobchan1915:20181108125833p:plain

CircliCI Registryに登録するための名前空間を作成する

以下のように名前空間を作成します。

Usage:
  circleci namespace create <name> <vcs-type> <org-name> [flags]

Args:
  <name>      名前空間。これはDockerHubでいうユーザーIDのようなものでCircliCI Registryではこれを持って識別します。
  <vcs-type>  Your VCS provider, can be either "github" or "bitbucket"
  <org-name>  組織の名前です。個人ならば`vcs-type`は`github`で`org-name`はGithubのアカウント名になります。

私の場合は以下のようになります。

circleci namespace create keisukeyamashita github KeisukeYamashita

=> 
Namespace `keisukeyamashita` created.
Please note that any orbs you publish in this namespace are open orbs and are world-readable.

Orbsを使う

Orbsは[namespace]/[orb]@[version] のフォーマットです。

Importするときは

orbs:
  slack: circleci/slack@0.1.0
  heroku: circleci/heroku@volatile

workflows:
  hello-workflow:
    jobs:
      - slack/some-job

のようにして宣言します。

ポイントとしては

  • orbs[]でimportして[orb名]/jobで使用する

ことを覚えれば大丈夫だと思います。

Orbsを作成する

現段階では、非常に公式ドキュメントがわかりにくいので、少しづつ解説してやります。

再利用可能なJobを作る

以下のようにJobを定義します。アンカーなどは説明しません。

version: 2.1

executors:
  default:
    docker:
      - image: circleci/golang:1.10
commands:
  dospecialthings:
    steps:
      - run: echo "We will now do special things"
jobs:
  myjob:
    executor: default
    steps:
      - dospecialthings

Orbをテスト

いくつかのレベルでテストをすることができる。

1. スキーマレベル

以下のコマンドでconfig.ymlのフォーマットがおかしくないかをチェックします。

circleci config validate

=> Config file at .circleci/config.yml is valid.

フォーマットは正しいことがチェックできました。

2. アンカーなどの展開テスト

以下のようにすると処理をすることができます。

一つのOrbをpublishして、他のconfig.yamlでimportして、正しく展開されるかをチェックします。

circleci config process .circleci/config.yml

Publishする

まずOrbを作成します。

circleci orb create keisukeyamashita/test-echo

=> 
Orb `keisukeyamashita/test-echo` created.
Please note that any versions you publish of this orb are world-readable.
You can now register versions of `keisukeyamashita/test-echo` using `circleci orb publish`.

以下のようにしてPublishします。有効なラベルと無効なラベルは以下の通りです。

  • 有効:
    • "dev:mybranch"
    • "dev:2018_09_01"
    • "dev:1.2.3-rc1"
    • "dev:myinitials/mybranch"
    • "dev:myVERYIMPORTANTbranch"
  • Invalid
    • "dev: 1" (空白が入ってはいけない)
    • "1.2.3-rc1" (devは必ず入れないといけない)
circleci orb publish .circle/config.yml keisukeyamashita/test-echo@dev:0.1

=> 
Orb `keisukeyamashita/test-echo@dev:0.1` was published.
Please note that this is an open orb and is world-readable.
Note that your dev label `dev:0.1` can be overwritten by anyone in your organization.
Your dev orb will expire in 90 days unless a new version is published on the label `dev:0.1`.

devラベルがついたものは公開はされません。組織内であれば誰でもupdateすることができます。

以下のようにして0.0.1にします。promoteコマンドは、productionレベルにあげるためのコマンドです。

circleci orb publish promote keisukeyamashita/test-echo@dev:0.1 patch

CircleCI Registyで確認します。

f:id:bobchan1915:20181108140923p:plain

また、CLIでも確認することができます。

circleci orb list -u | grep keisukeyamashita

=> 
keisukeyamashita/test-echo (0.0.1)

これによって変更することができないOrbが公開されました。

ソースは以下のように知ることができます。

version: 2.1
description: A test echo.

executors:
  default:
    docker:
      - image: circleci/golang:1.10
commands:
  dospecialthings:
    steps:
      - run: echo "We will now do special things"
jobs:
  myjob:
    executor: default
    steps:
      - dospecialthings

公開したOrbを使ってみる

以下のように使ってみます。

version: 2.1

orbs:
  test-echo: keisukeyamashita/test-echo@0.0.1

workflows:
  main:
    jobs:
      - test-echo/myjob

そして、正しく展開ができるかどうかをチェックします。

開発をするとき

devだろうとどれも公開されています。また、devproductionで異なるバージョンセマンティクスであるので注意が必要です。

ここはpromoteコマンドではpatchを使いましたが他にもminormajorがあり、アップデートの仕方を調整することができます。

f:id:bobchan1915:20181108143934p:plain

またincrementコマンドがあり、これは指定したバージョンセマンティックを自動で1だけ加算してくれます。

circleci orb publish increment .circleci/config.yml keisukeyamashita/test-echo patch 

=> Orb `keisukeyamashita/test-echo` has been incremented to `keisukeyamashita/test-echo@0.0.3`.
Please note that this is an open orb and is world-readable.

まとめ

devラベルとproductionラベルがあって、productionラベルは完全にImmutableなので開発のフローとしては非常にわかりやすかったです。

いずれはチームだけのPrivate Registyなどができてくれれば、より使いやすいのだろうなと思いました。

特にCI/CDはyaml管理問題には常に悩まされています。Orb自体も管理が面倒になるのではないかと思いました。

公開するメリットがなければ必要なさそうです。