Bitbucket Server (Stash) プラグイン開発

オンプレミス向けGitリポジトリ管理のソフトウェアの1つにBitbucket Server (旧Stash)があります。オンプレミスだとGitHub EnterpriseやOSSのGitBucket、GitLabを使っている方が多いかもしれませんが、Bitbucket ServerはJIRAで有名なAtlassian社の商用製品であり、10名までなら$10の買い切り価格と小規模なら激安で使うことができます。また、Atlassian Marketplaceで様々な有償/無償プラグインが公開されているのも特徴の一つ。本記事ではこのBitbucket Serverのプラグイン開発に関する情報をつらつらとまとめておきます。

なお、StashというのはBitbucket Serverのバージョン3までの名前です。昨年のバージョン4リリースのタイミングでStash → Bitbucket Serverに名称変更されています。名前が変わっただけ、といっても 大部分のパッケージ名やクラス名変更という最高に互換性のない変更 が行われたため、Stash時代に書かれたプラグイン開発情報を見て真似てもそのままではBitbucket Server向けには動作しないので要注意です。

プラグイン開発解説サイト

日本語

• Atlassian製品プラグイン作成事始め
• Stash プラグインの開発環境を構築するには

両方ともStashの頃に書かれた情報なので、最新のBitbucket Server向けのプラグインを開発したい方は要注意。ただしBitbucket Serverになっても基本的な開発の仕方は変わりません。上記サイトで書かれているAtlassian Plugin SDKを使用して開発します。

英語

Bitbucket Server Docsが開発者向けの公式サイト。ここから下記のような個別の解説記事へ辿ることができます。

• Installing the Atlassian SDK
• Creating a Bitbucket Server plugin
• Bitbucket Server Plugin Tutorials

初めての方はAtlassian Plugin SDKをとりあえずインストールし、チュートリアルを試してみると良いかと思います。ただし、Mavenを普段利用している方はStash プラグインの開発環境を構築するにはで書かれているようにsettings.xmlの置き換えをしておいたほうが無難です。後、インターネットに直接出れない環境の人はsettings.xmlにプロキシ設定を行うのを忘れずにしておくこと。

チュートリアルの中でAtlassian Plugin SDKが提供するコマンドatlas-*を実行するのですが、初回実行ではライブラリを数百MBダウンロードするためかなり時間がかかりますのでランチタイムに行く前に実行するなどが良いでしょう...

プラグインでできること

Bitbucket Server DocsにてPlugin typesとして、どういうことができるのか大体書かれています。

• Hosting Application Events
• Global Hooks
• Repository Hooks
• Global Merge conditions
• Repository Merge conditions
• Adding commit metadata

Gitリポジトリに対するpushをフックしたり、ブラウザからの操作(リポジトリ作成、ブランチ作成、プルリクエストの処理など)をフックすることができます。
プラグインで独自に画面を追加することもできますし、既存の画面を拡張するポイントも用意されている箇所があります。例えば、Adding a column to the branch listingというHow to記事では既存のブランチ一覧画面にカラムを追加する方法について解説しています。

開発環境

チュートリアルで登場しますが、Atlassian Plugin SDKをインストールすると入るatlas-runコマンドを実行するとローカルでBitbucket Serverが起動し、プラグインをビルド＆デプロイし動作確認することができます。なお、atlas-run-standaloneコマンドというものもあるのですが、こちらはプラグインの自動テプロイはしません。

atlas-runコマンドは初回はかなり遅いですが、2回目以降もそれなりに時間がかかります。そもそもBitbucket Serverの起動がめちゃくちゃ遅い。この遅さに耐えれなくてプラグイン開発を諦める人がでそうな気がするくらい遅い。一応、FastDevやQuickReloadというプラグインを動的に再インストールして効率化する方法があります。今後はFastDevは非推奨でQuickReloadが推奨のようですが、まだ解説しているサイトは少ないですし、Atlassian Plugin SDKが生成するプロジェクト雛形も今はまだFastDevをデフォルトで使っています。FastDevはリロードされないものがあったりとトラブルもあるようです。それを解決したのが後継のQuickReloadのようです。なお、Bitbucket Serverプラグイン開発でQuickReloadを利用するには、上記のFastDevだとリロードされない問題の解答が参考になります。

また、クラスのリロードに関してはお金を出してJRebelを使うというのも手です。圧倒的に速い。こちらで利用方法が解説されています。Bitbucket Server本体のJARの中にも何気にjrebel.xmlが格納されているものもあり、Atlassian社の開発者も使っていそうな気がします。

REST APIの利用

プラグインで開発する画面からJavaScriptでBitbucket Serverが提供するREST APIを呼び出し、様々なリソースを利用することができます。REST APIのドキュメントではJSON例も書かれていますので、読むとどういうAPIか大体想像ができるかと思います。

データの永続化

実装したいプラグイン内容によっては、何らかのデータを永続化したいこともあるでしょう。Bitbucket Server DocsのCommon tasksから下記情報へ辿れます。

• Storing data: active objects
• Storing data: plugin settings

後者は簡単なKey-Valueストアの仕組みであり、プラグインの設定情報の格納に利用すると良いでしょう。前者はActive ObjectsというORM (object relational mapping)を利用する汎用的な方式です。プラグインで独自にRDBMSにテーブルを定義して好きなデータを格納することができます。

画面開発

Bitbucket Server DocsのReferenceからWeb UI APIへ辿れます。画面(UI)を構成するAPIがたくさん用意されています。
特徴的なのはSoy APIというテンプレートAPIを使っているところでしょうか。

プラグイン実装例

Bitbucket Server DocsのReferenceからPlugin Module Typesを開くとプラグインサンプルやHow to記事がいくつかあるので参考になるかと思います。

また、OSSで公開されているプラグインもいくつかあるので、それらのソースを読むのも参考になるかと思います。Open source at Atlassianで紹介されていますし、GitHubでソース公開されているプラグインもあります(これとかこれ)。

(随時更新するかもしれません)