外部コードエディターの使用

ワークフロー API パッケージ

youtrack-scripting-api(英語) パッケージには、完全な YouTrack ワークフロー API が含まれています。このパッケージをコードエディターにプラグインすると、コード補完ツールは、API で利用可能なすべてのエンティティの有効な関数、メソッド、プロパティを提案します。

YouTrack アプリツール

youtrack-apps-tools(英語) パッケージには、外部コードエディターで作業する際に YouTrack アプリパッケージを管理するのに役立つユーティリティが含まれています。これにより、お好みの開発環境で JavaScript を使用して YouTrack 用のアプリやワークフローを作成および更新できます。

パッケージには、ローカルの変更を YouTrack インストールと同期させるスクリプトが含まれています。次のコマンドを使用できます。

パッケージのインストール

IDE でこれらのパッケージを使用するには、Node.js(英語) をインストールして実行する必要があります。これにより、プロジェクトでスクリプトパッケージを使用できる npm パッケージマネージャーもインストールされます。

次に、ワークフロー API パッケージとアプリツールを開発環境にインストールします。最も簡単な方法は、以下のコマンドを使用してパッケージをグローバルにインストールすることです。

開発環境に依存関係としてパッケージをインストールする場合は、次を入力します。

ご使用のインストールで、独自の認証局（CA）によって発行された証明書または自己署名証明書が使用されていない限り、個人の永久トークンを使用して接続を確立できます。Hub アカウントの認証タブで、独自の永久トークンを生成できます。手順については、永久トークンを作成するを参照してください。

既知の CA によって発行されていない証明書を使用している場合、Node.js 環境で特定の変数を使用して、IDE と YouTrack インストール間の接続を有効にする必要があります。手順については、SSL 証明書に関する特別な指示を参照してください。

カスタムワークフローが少数で、更新頻度もそれほど高くない場合は、基本的なコマンドで十分かもしれません。しかし、定期的な更新の場合、リクエストごとにホストとトークンを指定する必要があるのは少々面倒です。次のセクションの手順に従って、このプロセスを簡素化し、これらのコマンドをスムーズに使用してください。

環境変数の操作

接続情報を各コマンドに渡す代わりに環境変数に保存することで、アプリツールのコマンドを効率化できます。

youtrack-app コマンドは、以下の環境変数を読み取ります。

• YOUTRACK_HOST - YouTrack インストールのベース URL を指定します。myjetbrains.com でホストされている YouTrack Cloud インスタンスの場合は、末尾に /youtrack を含めます。

• YOUTRACK_API_TOKEN - YouTrack サービスへのアクセスを許可する永続的なトークン。

Hub アカウントの認証タブで、独自の永久トークンを生成できます。手順については、永久トークンを作成するを参照してください。

これらの値をシェルプロファイル、IDE 実行構成、シークレットマネージャーに保存してください。コマンドに --host または --token も渡した場合、コマンドラインの値が環境変数よりも優先されます。

最後のステップは、サポートされているコマンドを実行するスクリプトを作成することです。最も簡単な方法は、package.json ファイルを作成し、スクリプトを scripts フィールドに追加することです。

この package.json ファイルは、コマンドスクリプトと開発依存関係を格納する npm プロジェクトファイルです。アプリまたはワークフローパッケージの記述子ファイルは manifest.json です。

この時点では、ホスト名とトークンの値を指定せずにコマンドを実行できます。以下のコマンドを使用してスクリプトを実行してください。

• npm run list-prod

• npm run download-prod -- <app name>

• npm run upload-prod -- <directory>

基本的なプロセスは次のとおりです。

1. download コマンドを使用して、アプリケーションパッケージをインストール環境から開発環境にコピーします。

2. 変更を加えます。

3. upload コマンドを使用して、YouTrack のアプリパッケージを更新します。

アップデートは依然として本番環境に直接適用されることに注意してください。より管理された方法で作業を進めたい場合は、次のセクションの手順に従ってください。

テスト環境への接続

外部エディターを使用してワークフローを作成する主な利点の 1 つは、複数の YouTrack インストールに接続できることです。他のコード開発プロジェクトと同様に、最初にサンドボックス環境で変更をアップロードしてテストする必要があります。意図したとおりに機能していることが確実な場合にのみ、本番環境でコードをデプロイしてください。

独自のサンドボックス環境を作成することをお勧めします。無料プランは、ワークフローをテストするための優れたソリューションです。

• 実稼働環境が YouTrack サーバーのインストールである場合は、ローカルコピーをダウンロードしてインストールし、無料プランを使用できます。ローカルインストールを実稼働環境と同じバージョンに更新して、ワークフローが期待どおりに動作するようにすることができます。

• YouTrack クラウドをご利用の場合は、無料プランをご利用の別のインスタンスにご登録いただけます。ホストされているサーバーは、YouTrack の最新バージョンに自動的にアップグレードされます。

テスト環境でアカウントを設定したら、アプリツールコマンドを実行する際に、テスト環境の値を使用できます。

一般的なプロセスは次のようになります。

1. 以下のコマンドを使用して、本番環境からアプリパッケージをダウンロードします。

   npm run download-prod -- <app name>

2. IDE でワークフローを更新します。

3. YOUTRACK_HOST と YOUTRACK_API_TOKEN の値を、ご使用のテスト環境に合わせて変更してください。

4. 以下のコマンドを使用して、変更したパッケージをテスト環境にアップロードしてください。

   npm run upload-prod -- <directory>

5. YouTrack サンドボックス環境でワークフローをテストします。

6. ワークフローが期待どおりに動作するまで、手順 2 ～ 5 を繰り返してください。

7. YOUTRACK_HOST と YOUTRACK_API_TOKEN を、ご使用の運用環境の値に戻してください。

8. 最終バージョンのパッケージを以下のコマンドで本番環境にアップロードしてください。

   npm run upload-prod -- <directory>

YouTrack インストールのカスタマイズを担当するのがあなただけである場合は、ここで停止ことができます。この設定により、お気に入りの開発環境でのみ作業しながら、ワークフローを安全に更新できます。

組織内に独自のプロジェクト用のスクリプトを作成する他の開発者がいる場合は、全員が一緒に作業できるようにすることができます。次のセクションの指示に従って、この設定をチームと共有してください。

チームとして働く

このセクションで紹介する設定の最大の利点の 1 つは、コラボレーションをサポートしている点です。いくつかの変更を加えるだけで、他の開発者が YouTrack 環境内のワークフローを管理するために使用できるプラットフォームを構築できます。この設定は特定の環境に限定されないため、開発者はどのオペレーティングシステムでも JavaScript をサポートする IDE を使用できます。

まず最初にできることは、共有の npm package.json ファイルをコミットすることです。この設定を使用する各開発者は、それぞれ独自の個人トークンを生成して保存する必要がありますが、スクリプトは全員で共有できます。

次の例を参考にしてください。

スクリプトは YOUTRACK_HOST と YOUTRACK_API_TOKEN からホスト名とトークンを読み取ります。これにより、各開発者は共有プロジェクトファイルを変更することなく、ローカル環境内のターゲットとなる YouTrack インストールを選択できます。

最後のステップは、プロジェクトをリポジトリにアップロードすることです。プロジェクトをリポジトリにアップロードすると、他のユーザーは次の手順に従ってコーディングを開始できます。

• リポジトリに接続し、プロジェクトのローカルコピーをダウンロードしてください。プロジェクトファイルに npm package.json ファイルを含めるようにしてください。

• ユーザーが使用する YouTrack インストール用の個人用永久トークンを生成し、環境変数として保存します。

これで、各開発者は次のアクションを実行できるようになります。

• リポジトリからプロジェクトファイルをダウンロードします。

• ローカル環境でワークフロースクリプトを更新します。

• 期待どおりに動作するまで、更新をサンドボックスにアップロードしてテストします。

• 改訂されたスクリプトを実稼働環境にアップロードします。

• 変更内容をリポジトリにプッシュし、改訂されたスクリプトのバージョンを更新します。

実際の例については、YouTrack カスタムワークフローリポジトリ(英語)を参照してください。ここでは、YouTrack のデフォルトワークフローではカバーされないさまざまなユースケースをサポートするワークフローをアップロードします。リポジトリからスクリプトをダウンロードして、特定のビジネスケースに合うようにスクリプトを調整することは誰でも歓迎です。コミュニティと共有したいスクリプトがある場合は、プルリクエストを送信してください !

SSL 証明書に関する特別な指示

YouTrack ドメインが既知の認証局によって発行された SSL 証明書を使用する場合、個人の永久トークンのみを使用して接続を確立できます。証明書は、Node.js に組み込まれている CA 証明書ストアにすでに含まれています。自動的に認識されない、または自己シグネチャーされた CA によって発行された証明書の場合、証明書を認識または無視するように Node.js の環境変数を変更する必要があります。