こんにちは。
エンジニアの遠藤です。

弊社では、 CI/CD プラットフォームとして、 Bitrise を使うケースがあります。
以下の記事でも連携手順などをまとめていますが、 self-hosted gitlab と連携しています。
https://note.milldea.com/posts/bitrise-gitlab-connection-guide

Bitrise には便利な面もあるのですが、個人的に不便だなと思う点があり、それがワークフローの履歴を管理できない点でした。

今回は、 self-hosted gitlab 上で、 bitrise.yml を管理する手順をまとめてみたいと思います。

この操作は、 Bitrise では Owner 権限が、 Gitlab では Admin 権限が必要です。

背景

ワークフローの編集は Bitrise の UI で編集できるのですが、内部的には bitrise.yml という yaml 形式のファイルで定義されています。
Bitrise の標準機能として、現在のバージョンと過去のある時点でビルドしたバージョンとの差分を見ることはできます。

----------2024-07-05-10.54.31

ただし、コメントを残せないので、なぜその変更が必要だったかは分かりません。
次に変更が入っているビルドバージョンはどれなのかも分からないので、一つずつ確認する必要があります。
また、特定のビルドバージョンとの比較などもできません。

この辺りが不便だなと思い、公式のドキュメントなどを調べていたところ、 git リポジトリ側でも管理できるよ、とありましたので、やってみました。
https://devcenter.bitrise.io/ja/builds/configuring-build-settings/managing-an-app-s-bitrise-yml-file.html

連携したい Bitrise 側の「App Settings」で、「Integrations」がすでに以下のようになっている場合は、認証のステップは完了していますので、「bitrise.yml を移行する」までスキップできます。

----------2024-07-05-11.51.48

以下のように、そもそも項目が表示されていない場合は、連携できていませんので、認証から設定します。

----------2024-07-05-11.52.41

事前準備

gitlab 側で IP制限などをかけている場合は、事前に以下の IP アドレスからのアクセスを許可するように設定してください。
https://devcenter.bitrise.io/ja/infrastructure/build-machines/configuring-your-network-to-access-our-build-machines.html

認証

まず初めに Bitrise アカウントと Self-hosted GitLab を連携させておく必要があります。
この手順は、 Bitrise に登録したアプリが ssh key などで gitlab リポジトリにアクセスできていたとしても必要です。

Bitrise の Callback URL の確認

Bitrise へ Owner 権限でログインし、「Settings」→「Integrations」→「Git provider」へと進みます。
----------2024-07-04-14.47.23

下へスクロールすると、「Self-hosted GitLab」の欄があり Gitlab に登録する callback URL が表示されていますので、コピーしておきます。

----------2024-07-04-14.47.32_

個々の設定がすでに以下のように「Disconnect」になっている場合は、登録が完了していますので、次のアプリケーションの追加はスキップしてください。

----------2024-07-05-11.27.14

※ なお、こちらの「Disconnect」を押すと、元々の設定がなんだったかも分からず、警告も出ずに消えますのでご注意ください。

Gitlab へのアプリケーションの追加

Gitlab へログインし、「Admin Area」→「Applications」→「New application」を選びます。

----------2024-07-04-14.44.28

アプリケーションの追加画面に遷移しますので、こちらで必要な情報を登録してください。
アプリケーションは、 Admin Area ではなく個人でも登録することができますが、おそらく個人で登録してしまうと別のユーザが認証できなくなってしまうので、組織全体で使える Admin Area に登録しておくのが良さそうです。

権限は、「api」にチェックを入れます。

----------2024-07-04-14.46.34

登録に成功すると、「Application ID」, 「Secret」が発行されますので、自社の gitlab の URL と共に Bitrise へ登録します。

----------2024-07-04-14.47.01

Bitrise の表記が以下のようになっていれば設定が保存されています。

----------2024-07-05-11.27.14

自分の Bitrise アカウントと gitlab アカウントを連携させる

ここまでの手順で Bitrise のワークスペースに gitlab の情報を設定できました。
続けて、自分の Bitrise アカウントが gitlab にアクセスできるように設定します。

Bitrise の右上のメニューから、「Account settings」へ進みます。
----------2024-07-05-11.43.26

「Self-hosted GitLab accounts」を参照すると、連携可能な gitlab アカウントが表示されていますので、 Switch を押します。

----------2024-07-05-11.45.12

ここで、登録が成功していると、 Gitlab 側で承認してよいか確認されますので、問題なければ承認します。

----------2024-07-04-14.48.22

ここまでで、認証の準備が完了となります。

bitrise.yml を移行する

ここまで設定できてれば、公式の手順通りなので、やることは多くありません。
まずは、各アプリの Workflow 編集画面に進みます。

----------2024-07-05-11.57.50

左ペインのメニューに「bitrise.yml」があるので、押下します。

----------2024-07-05-11.58.36

ここで bitrise.yml をダウンロードして、 git リポジトリの default ブランチのプロジェクトルートに保存します。

bitrise.yml の保存先が「Store on bitrise.io」になっていると思いますので、これを「Store in app repository」に変更して、「Update settings」を押下します。

----------2024-07-03-13.42.44

ここまでの設定がうまくできていれば、問題なく保存できます。
認証などに失敗していると、保存できずにエラーが出ます。

手元で編集する

さて、以上で yml を gitlab で保存できるようになったのですが、 Bitirse の UI で操作できる機能も便利です。

git で保存して、 push して Bitrise 上で正しいフォーマットになっているか確認する、という手順は面倒だと思います。
何かいいツールはないかと探していたところ、ちゃんと公式から cli ツールが提供されていました。

https://devcenter.bitrise.io/en/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor.html

Mac であれば、 brew でインストール

$ brew update && brew install bitrise

初期セットアップ

$ bitrise setup

bitrise.yml の保存してあるディレクトリ（普通はプロジェクトルート）まで移動

$ cd your_repository

以下のコマンドで workflow-editor を起動

$ bitrise :workflow-editor

これだけで、ローカルにエディタが表示されて編集できます。

----------2024-07-03-11.08.16

また、 bitrise cli は local で workflow を実行することもできそうなので、試行錯誤したい時などは、このまま手元で軽く動作確認などまでしてしまうのが良さそうです。

運用はどう変わる？

local の編集を反映させるには

手元で編集した内容を、 Bitrise に設定したデフォルトブランチに push すると、自動的に Workflow が反映されます。

Web 上で編集できる？

できません。
編集して保存しようとすると、コピペするかダウンロードして main ブランチを更新してね、と言われます。
----------2024-07-08-22.51.04

ここで、「I'm done」を押下すると、画面が自動でリロードされて main ブランチを読み込みに行きます。
Web 上の変更は即座に消えるので注意してください。

さいごに

認証の部分で少しハマってしまいましたが、設定さえしてしまえば、簡単に連携できました。
ちょっとした修正を確認するのに、 main ブランチに push するのはやや手間が増えるようにも感じます。
手軽に Web 上で変更できるというメリットを捨てることにはなりますが、コードの管理と同じくらい CI/CD の設定は重要だと考えています。
ワークフローが大規模になりそうな時や、似たようなプロジェクトで使いまわせそうな時などは、 git で管理し、ノウハウを貯めていきたいと思いました。