はじめに
CI/CDサービスのBitriseでは複数のStepを利用してワークフローを作成します。
このStepは「アプリのビルド」や「Slack通知」といったことができるものなどいろいろとあります。
しかし、求めているStepがあるとは限りません。
その場合、例えばシェルスクリプトを実行するStepを利用して、独自に処理を書く場合があります。
しかし、汎用的に利用できるような処理の場合はStepを作ってしまうのも手です。
そこで本稿では、そのBitriseのStepの作り方を明記していきます。
※Bitriseの公式ドキュメントが参考になりますが、日本語版だと情報が足りてない箇所があったりするので、注意してください※
作り方の大まかな流れは次のとおりです。
これらを順に説明していきます。
- （１）セットアップ
- （２）Stepの開発
- （３）Stepの公開
（１） セットアップ
BitriseのStepを作るために事前におこなう必要があることを説明していきます。
Bitrise CLIのインストール
参考：https://devcenter.bitrise.io/jp/bitrise-cli/installation/
下記はbrewでインストールした例です。
$ brew install bitrise
$ bitrise --version
1.47.2
Step用ディレクトリの作成
次のコマンドを実行していきます。
$ bitrise setup
$ bitrise plugin update step
$ bitrise :step create
この最後のコマンドを実行するとtemplateが生成されます。
その際にいくつかの質問を答える必要があります。
Stepで利用する言語は「bash」と「go」から選ぶことができます。
bashを選んだ場合に生成されるファイルは次のとおりです。
- .bitrise.secrets.yml
- bitrise.yml
- step.sh
- step.yml
- README
- LICENSE
- .gitignore
（２） Stepの開発
上記の生成されたファイルを元にStepの開発の仕方を説明していきます。
（２−１） 構成について
bashを選択した場合に初期に作られるディレクトリ構成は次のとおりです。
- .bitrise.secrets.yml（※３）
- bitrise.yml（※４）
- step.sh（※１）
- step.yml（※２）
- README
- LICENSE
- .gitignore
Stepを開発する際にメインで使うのは（※１）と（※２）です。
（※３）と（※４）は主にテスト時に利用します。
goを選択した場合の構成では、step.shがmain.goに変わります。
（２−２） step.shとstep.ymlの編集
Stepで実行する内容に関しては、step.sh に記載していきます。
このシェルスクリプト内で利用する値については、step.ymlで定義することができます。
inputs:
- sample_token:
opts:
title: 表示されるタイトル
summary:
description: |-
説明を記載
is_required: true
is_sensitive: true
このように記載すると、step.shではsample_token環境変数が利用できるようになります。
また、optsで指定している２つのkeyの用途については次のとおりです。
- is_required：この値が必須かどうか（true：必須）
- is_sensitive：trueの場合、Secrets環境変数の使用のみの許可
Stepで生成される環境変数についてはstep.ymlの中で次のように定義することができます。
いろいろなStepが後続のStepで利用できるようにそのStep自身での成果物に対する環境変数を定義しています。
outputs:
- SAMPLE_OUTPUT:
opts:
title: 表示されるタイトル
summary:
description:
summaryとdescriptionに関しては現時点でBitriseで表示されてないように見えています（が、どこかで表示されているのでしょうか？）
（２−３） テスト（動作確認）
参考：https://devcenter.bitrise.io/jp/contributors/testing-and-versioning-your-steps/
作成したStepは公開する前に動作確認することは重要です。
テストについては次のやり方があります。
- （２−３−１） 手元での実行
- （２−３−２） GitHubのリポジトリを指定しての実行
- StepLibリポジトリを指定しての実行
- 今回は割愛します
（２−３−１） 手元での実行
次のコマンドを実行することで手元で作ったStepの動作確認をおこなうことができます。
$ cd my_step_directory
$ bitrise run test
上記のコマンドを実行すると手元の環境でbitrise.yml にある test という名前がついているワークフローが動きます。
（bitrise.ymlについての情報は https://devcenter.bitrise.io/bitrise-cli/basics-of-bitrise-yml/ を参考にしてください）
Stepで利用するパラメータを指定したい場合は、bitrise.ymlでinputs: を更新します。
- path::./:
title: Step Test
description: |-
The example input has a default value,
you can overwrite it if you want to, just like we did below,
but the step would use the default value specified in the `step.yml`
file if you would not specify another value.
run_if: true
inputs:
- example_step_input: Example Step Input's value
Secrets環境変数を使いたい場合は、.bitrise.secrets.ymlに定義します。
このコマンドを実行すると次のような感じの結果が出ます。
ローカルでのテストは実行の気軽さ、早さ的にもおこなうのが良いです。
ただし、注意すべき点としては、実際のBitriseの環境とは異なりセットアップされているアプリケーションも同一ではないため、必ずしも結果が一致するとは限らないということです。
そのため、他に実際にBitriseの環境で実行するという方法もあります。
（２−３−２） GitHubのリポジトリを指定しての実行
Bitriseの審査を通す前に実際に試す方法として、GitHubのリポジトリを直接指定して利用することができます。
bitrise.ymlで次のようにGitHubのアドレスとブランチを指定します。
※ただしpublicなリポジトリである必要があります。
- git::[GitHubのアドレス]@main:
inputs:
- 入力パラメータ：入力値
inputsの箇所がstepで利用できる入力パラメータとなります。
これにより実際のBitriseの環境で動作確認をすることが出来ます。
（２−４） アイコン（オプション）
Stepを追加時に表示されるStepのアイコンは次の要件を満たしている必要があります。
- Its background color should not be transparent.
- Size: 256x256 px.
- Margin: 60 px.
- Format: SVG.
作成したアイコンの置き場所は、Stepのために作成したリポジトリとは別の場所に保存することになります。
作成したアイコンは、次の場所に置いておきます。
次の場所の詳細については（３）のStepの公開で言及しています。
STEPLIB_FORK_ROOT/steps/YOUR_STEP_ID/assets/icon.svg
（３） Stepの公開
作成したStepをBitriseで利用するには次の方法があります。
- （３−１）別途用意したStepLibを指定して利用
- （３−２）GitHubのリポジトリを直接指定の利用
- ここでは割愛
- （３−３）BitriseのStepを一般公開
- Bitriseのワークフローから検索して誰もが利用できる
これらのうち（３−１）については上述したとおりです。
ここでは（３−３）について説明をしていきます。
（３−３）BitriseのStepを一般公開
BitriseのStepを公開する流れとしては次のとおりです。
コマンドを実行した際のログに何を行ったか、次に何をおこなうかが記載されているので、ログもちゃんとチェックしましょう。
１．Step本体のリポジトリにタグをきっておく
このタグ名はあとで利用します（step-version-tagとします）。
２．StepLibをForkする
https://github.com/bitrise-io/bitrise-steplib
をForkしておきます。
３．コマンドの実行（１）
Forkしたアドレスを指定して次を実行します。
$ bitrise share start -c https://github.com/[your-username]/bitrise-steplib.git
-cオプションのアドレス指定は git@github.com:[your-username]/bitrise-steplib.git でもOKです。
４．コマンドの実行（２）
１で指定したタグ名とStepのGitHubのリポジトリとStepのIdを指定して次を実行します。
$ bitrise share create --tag [step-version-tag] --git [step-git-uri].git --stepid [step-id]
手元にあるStepLibに追加された step.yml ファイルをチェックします。
問題なければ次のステップに進んでいきます。
５．アイコンの用意（オプション）
アイコンを追加する場合は、生成されたbranchの次の場所に対して用意しておいたアイコンを置きます。
STEPLIB_FORK_ROOT/steps/YOUR_STEP_ID/assets/icon.svg
６．コマンドの実行（３）
$ bitrise share finish
このコマンドを実行すると変更内容を指定したStepLibに特定ブランチ名（[step-id]-[step-version-tag]）でpushしてくれます。
７．プルリクエストの作成
生成されたブランチを元にBitriseのStepLibリポジトリに対してプルリクエストを出します。
８．レビュー対応
Bitriseの方がコードレビューをしてくれます。
指摘された内容などを対応し、最終的にmergeされればBitriseから利用できるようになります。
おわりに
今後、Stepを作る機会が定期的にありそうなので備忘録も兼ねて書いてみました。
また、Stepを作る際に本記事を読んでわからない箇所があれば随時追記していこうと思います。
このStepですが、Bitriseにおいて重要な機能です。
ぜひとも便利なStepをどんどんと公開して、さらに便利にしていきましょう。
参考資料
- Bitriseの公式ドキュメント（Stepの作り方）
- Stepのテストの仕方
- bitrise.ymlについて