ビルド、テスト、展開用の独自のツールを Code Streamに統合する方法

DevOps 管理者または開発者は、カスタムスクリプトを作成して、 Code Streamの機能を拡張できます。

カスタムスクリプトを使用すると、 Code Streamを独自の継続的インテグレーション (CI) および継続的デリバリ (CD) ツールと API に統合して、アプリケーションをビルド、テスト、および展開できます。カスタムスクリプトは、アプリケーション API を公開しない場合に特に便利です。

カスタムスクリプトでは、ビルド、テスト、展開の各ツールを Code Streamと統合するために必要なことをほぼすべて実行できます。たとえば、スクリプトでパイプラインのワークスペースを利用することで、アプリケーションをビルドしてテストする継続的インテグレーションタスクと、アプリケーションを展開する継続的デリバリタスクをサポートできます。パイプラインの終了時にスラックにメッセージを送信するなど、さまざまなことができます。

Code Stream パイプラインワークスペースでは、継続的インテグレーションタスクとカスタムタスクで Docker と Kubernetes がサポートされます。

ワークスペースの構成に関する詳細については、パイプラインワークスペースの構成を参照してください。

カスタムスクリプトを記述するには、サポートされている言語のいずれかを使用します。スクリプトにビジネスロジックを含めて、入力と出力を定義します。出力タイプには、数値、文字列、テキスト、およびパスワードを含めることができます。異なるビジネスロジック、入力、および出力を使用して、複数のバージョンのカスタムスクリプトを作成できます。

作成したスクリプトは、 Code Streamインスタンスに保存されます。YAML コードをインポートしてカスタム統合を作成したり、スクリプトを YAML ファイルとしてエクスポートして別の Code Streamインスタンスで使用したりできます。

カスタムタスクで、パイプラインによってスクリプトのリリースバージョンを実行します。複数のリリースバージョンがある場合は、そのうちの 1 つを最新として設定することで、カスタムタスクを選択したときにそのバージョンに [latest -->] と表示されるようになります。

パイプラインでカスタム統合が使用されている場合、カスタム統合を削除しようとすると、エラーメッセージが表示され、削除できないことが示されます。

カスタム統合を削除すると、カスタムスクリプトのすべてのバージョンが削除されます。既存のパイプラインに、そのスクリプトのいずれかのバージョンを使用するカスタムタスクがある場合、パイプラインは失敗します。既存のパイプラインが失敗しないようにするために、不要になったスクリプトのバージョンを廃止して、取り消すことができます。そのバージョンを使用しているパイプラインがない場合は、削除できます。

表 1. カスタムスクリプトを記述した後の操作
操作	操作の詳細情報
パイプラインにカスタムタスクを追加します。	カスタムタスク：パイプラインの他の CI タスクと同じコンテナで実行されます。パイプラインがカスタムタスクを実行する前に、スクリプトでポピュレートする入出力変数を含めます。複数のデータタイプとさまざまなタイプのメタデータをスクリプトに入力および出力として定義できます。
カスタムタスクでスクリプトを選択します。	スクリプトで入力および出力プロパティを宣言します。
パイプラインを保存し、有効にして実行します。	パイプラインを実行すると、カスタムタスクによって指定されたスクリプトのバージョンが呼び出され、そこでビジネスロジックが実行されます。これにより、ビルド、テスト、展開の各ツールが Code Streamと統合されます。
パイプラインの実行後、実行結果を確認します。	想定どおりの結果であるかを確認します。

カスタム統合バージョンを呼び出すカスタムタスクを使用する場合は、パイプラインの [ワークスペース] タブで、カスタム環境変数を名前と値のペアとして指定できます。CI タスクを実行してイメージを展開するワークスペースコンテナがビルダーイメージによって作成されると、そのコンテナに Code Streamが環境変数を渡します。

たとえば、 Code Streamインスタンスが Web プロキシを必要とする場合に、Docker ホストを使用してカスタム統合のためのコンテナを作成すると、 Code Stream がパイプラインを実行し、Web プロキシ設定変数をそのコンテナに渡します。

表 2. 環境変数の名前と値のペアの例
名前	値
HTTPS_PROXY	http://10.0.0.255:1234
https_proxy	http://10.0.0.255:1234
NO_PROXY	10.0.0.32, *.dept.vsphere.local
no_proxy	10.0.0.32, *.dept.vsphere.local
HTTP_PROXY	http://10.0.0.254:1234
http_proxy	http://10.0.0.254:1234
PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

このように、名前と値のペアがユーザーインターフェイスに表示されます。

Code Stream は、ビルダーイメージが作成するコンテナに環境変数を渡します。

この例では、 Code Streamをスラックインスタンスに接続してメッセージをスラックチャネルにポストするカスタム統合を作成します。

前提条件

カスタムスクリプトを記述する場合は、Python 2、Python 3、Node.js のいずれかの言語か、Bash、sh、zsh のいずれかのシェル言語を使用できることを確認してください。
インストールされた Node.js または Python のランタイムを使用して、コンテナイメージを生成します。

手順

カスタム統合を作成します。

[カスタム統合] > [新規] の順にクリックし、適切な名前を入力します。
優先するランタイム環境を選択します。
[作成] をクリックします。
スクリプトが開き、コードが表示されます。コードには、必要なランタイム環境が含まれています。たとえば、 runtime: "nodejs"です。スクリプトには、ビルダイメージが使用するランタイムを含める必要があります。これにより、パイプラインの実行時に、パイプラインに追加したカスタムタスクが正常に実行されます。これを行わない場合、カスタムタスクは失敗します。

カスタム統合 YAML の主な領域は、ランタイム、コード、入力プロパティ、および出力プロパティなどです。この手順では、さまざまなタイプと構文について説明します。


カスタム統合 YAML のキー	説明
runtime	Code Streamがコードを実行するタスクランタイム環境。次のいずれかの文字列を使用することができ、大文字と小文字は区別しません。 nodejs python2 python3 shell 何も指定しなかった場合は、shell がデフォルトとして使用されます。
code	カスタムタスクの一部として実行するカスタムビジネスロジック。
inputProperties	カスタムタスク構成の一部としてキャプチャする入力プロパティの配列。これらのプロパティは、通常はコード内で使用されます。
outputProperties	カスタムタスクからエクスポートしてパイプラインに伝達できる出力プロパティの配列。

スクリプトで入力プロパティを宣言するときには、有効なデータタイプおよびメタデータを使用します。

入力プロパティは、YAML の code:セクションでスクリプトにコンテキストとして渡されます。


カスタムタスク YAML の入力キー	説明	必須
`type`	レンダリングする入力のタイプ： `text` `textarea` `number` `checkbox` `password` `select`	はい
`name`	カスタムタスクに対する入力の名前または文字列。カスタム統合 YAML コードに取り込まれます。カスタム統合用に定義された入力プロパティごとに一意である必要があります。	はい
`title`	パイプラインモデルキャンバス上のカスタムタスクに対する入力プロパティのテキスト文字列ラベル。空白のままにすると、デフォルトで `name` が使用されます。	いいえ
`required`	ユーザーがカスタムタスクを設定するときに入力プロパティを入力する必要があるかどうかを決定します。true または false に設定します。true の場合に、パイプラインキャンバスでカスタムタスクを設定するときにユーザーが値を指定しなければ、タスクの状態は未構成のままになります。	いいえ
`placeHolder`	値がない場合の入力プロパティエントリ領域のデフォルトテキスト。html プレースホルダ属性にマッピングされます。特定の入力プロパティタイプでのみサポートされます。	いいえ
`defaultValue`	パイプラインモデル画面でカスタムタスクがレンダリングされるときに、入力プロパティエントリ領域に入力されるデフォルト値。	いいえ
`bindable`	パイプラインキャンバスでカスタムタスクをモデリングするときに、入力プロパティがドル記号の変数を受け入れるかどうかを決定します。タイトルの横に [$] インジケータを追加します。特定の入力プロパティタイプでのみサポートされます。	いいえ
`labelMessage`	ユーザーのヘルプツールチップとして機能する文字列。入力タイトルの横にツールチップアイコン [i] を追加します。	いいえ
`enum`	特定の入力プロパティオプションを表示する値の配列を取得します。特定の入力プロパティタイプでのみサポートされます。ユーザーがオプションを選択して、カスタムタスク用に保存した場合は、[inputProperty] 値がこの値に対応して、カスタムタスクのモデリング中に表示されます。たとえば、値として 2015 を使用します。 2015 2016 2017 2018 2019 2020	いいえ
`options`	[optionKey] および [optionValue] を使用して、オブジェクトの配列を取得します。 [optionKey]：タスクのコードセクションに伝達される値。 [optionValue]：ユーザーインターフェイスにオプションを表示する文字列。特定の入力プロパティタイプでのみサポートされます。オプションは、次のとおりです。 [optionKey]：key1：カスタムタスク用に選択して保存した場合、この inputProperty の値はコードセクションの [key1] に対応します。 [optionValue]：「1 のラベル」。ユーザーインターフェイスの [key1] の値を表示します。カスタムタスクのほかの場所には表示されません。 [optionKey]：key2 [optionValue]：「2 のラベル」。 [optionKey]：key3 [optionValue]：「3 のラベル」。	いいえ
`minimum`	この入力プロパティの有効な最小値として機能する値を取得します。数値タイプの入力プロパティでのみサポートされます。	いいえ
`maximum`	この入力プロパティの有効な最大値として機能する値を取得します。数値タイプの入力プロパティでのみサポートされます。	いいえ

表 3. カスタムスクリプトでサポートされるデータタイプとメタデータ
サポートされるデータタイプ	入力でサポートされるメタデータ
文字列テキストリスト：任意のタイプのリストマップ： map[string]any セキュア：カスタムタスクを保存するときに暗号化されるパスワードテキストボックスとして表示されます。数値ブール値：テキストボックスとして表示されます。 URL：文字列と同じですが、検証が追加されています。選択肢、ラジオボタン	type：String \| Text ... のいずれか default：デフォルト値 options：オプションのリストまたはマップ。選択肢またはラジオボタンで使用されます。 min：最小値または最小サイズ max：最大値または最大サイズ title：テキストボックスの詳細な名前 placeHolder：ユーザーインターフェイスプレースホルダ description：ツールチップになります。

例：

inputProperties:
        - name: message
          type: text
          title: Message
          placeHolder: Message for Slack Channel
          defaultValue: Hello Slack
          bindable: true
          labelInfo: true
          labelMessage: This message is posted to the Slack channel link provided in the code

スクリプトで出力プロパティを宣言します。

出力プロパティはスクリプトのビジネスロジック code:セクションからキャプチャされるため、ここに出力のコンテキストを宣言します。

パイプラインの実行時に、タスク出力の応答コードを入力できます。たとえば、 200 です。

Code Streamが [outputProperty] ごとにサポートされるキー。


key	説明
type	現在は、単一値 `label` が含まれています。
name	カスタム統合 YAML のコードブロックによって送信されるキー。
title	[outputProperty] を表示するユーザーインターフェイスのラベル。

例：

outputProperties:
  - name: statusCode
    type: label
    title: Status Code

カスタムスクリプトの入力および出力を操作するには、context を使用して、入力プロパティを取得するか、出力プロパティを設定します。

入力プロパティの場合： (context.getInput("key"))

出力プロパティの場合： (context.setOutput("key", "value"))

Node.js の場合：

var context = require("./context.js")
var message = context.getInput("message");
//Your Business logic
context.setOutput("statusCode", 200);

Python の場合：

from context import getInput, setOutput
message = getInput('message')
//Your Business logic
setOutput('statusCode', '200')

Shell の場合：

# Input, Output properties are environment variables
echo ${message} # Prints the input message
//Your Business logic
export statusCode=200 # Sets output property statusCode

code:セクションで、カスタム統合のすべてのビジネスロジックを宣言します。

たとえば、Node.js ランタイム環境では次のようになります。

code: |
    var https = require('https');
    var context = require("./context.js")
    
    //Get the entered message from task config page and assign it to message var
    var message = context.getInput("message");
    var slackPayload = JSON.stringify(
        {
            text: message
        });

    const options = {
        hostname: 'hooks.slack.com',
        port: 443,
        path: '/YOUR_SLACK_WEBHOOK_PATH',
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': Buffer.byteLength(slackPayload)
        }
    };
    
    // Makes a https request and sets the output with statusCode which 
    // will be displayed in task result page after execution
    const req = https.request(options, (res) => {
        context.setOutput("statusCode", res.statusCode);
    });

    req.on('error', (e) => {
        console.error(e);
    });
    req.write(slackPayload);
    req.end();

カスタム統合スクリプトをバージョン化してリリースする前に、Python または Node.js のコンテキストファイルをダウンロードし、スクリプトに含まれているビジネスロジックをテストします。
1. キャンバスの上部にポインタを置き、コンテキストファイルボタンをクリックします。たとえば、スクリプトが Python に含まれている場合は、[CONTEXT.PY] をクリックします。
2. ファイルを変更して保存します。
3. 開発システムで、コンテキストファイルを利用してカスタムスクリプトを実行し、テストします。
カスタム統合スクリプトにバージョンを適用します。
1. [バージョン] をクリックします。
2. バージョン情報を入力します。
3. [リリースバージョン] をクリックして、カスタムタスクでスクリプトを選択できるようにします。
4. バージョンを作成するには、[作成] をクリックします。
（オプション） カスタム統合スクリプトのいずれかのリリースバージョンを最新として設定すると、パイプラインキャンバスでそのバージョンに [latest -->] ラベルが表示されるようになります。
1. キャンバスの上部にポインタを置き、[バージョン履歴] をクリックします。
2. 使用可能なアクションを表示するには、目的のバージョンの横向き省略記号をクリックし、[最新として設定] を選択します。
  
  注： [最新として設定] アクションでは、リリースバージョンのみが表示されます。
3. バージョンの選択を承認するには、[最新として設定] をクリックします。
4. [バージョン履歴] を終了してスクリプトエディタキャンバスに戻るには、戻る矢印をクリックします。
スクリプトを保存するには、[保存] をクリックします。
スクリプトを YAML ファイルとしてエクスポートして別の Code Streamインスタンスで使用するには、カスタム統合カードで [アクション] > [エクスポート] の順にクリックし、エクスポートするバージョンを選択します。
パイプラインで、ワークスペースを構成します。
この例では、Docker ワークスペースを使用します。
1. [ワークスペース] タブをクリックします。
2. Docker ホストおよびビルダイメージ URL を選択します。
パイプラインにカスタムタスクを追加して設定します。
1. [モデル] タブをクリックします。
2. タスクを追加し、タイプとして [カスタム] を選択し、適切な名前を入力します。
3. カスタム統合スクリプトとバージョンを選択します。スクリプトのいずれかのバージョンが最新として設定されている場合、そのバージョンにはバージョン名の前に [latest -->] と表示されます。
4. スラックにカスタムメッセージを表示するには、メッセージテキストを入力します。
  入力したテキストでカスタム統合スクリプトの defaultValueがオーバーライドされます。
パイプラインを保存して有効にします。
1. [保存] をクリックします。
2. パイプラインカードで、[アクション] > [有効] の順にクリックします。
パイプラインを実行します。
1. [実行] をクリックします。
2. パイプラインの実行状況を確認します。
3. ステータスコード、応答コード、ステータス、および宣言出力が想定どおりであることを確認します。
  出力プロパティとして [statusCode] を定義しました。たとえば、 [statusCode] が 200 であれば、スラックのポストが正常に完了したことになり、 [responseCode] が 0 であれば、スクリプトがエラーなしで正常に完了したことになります。
4. 実行ログで出力を確認するには、[実行] をクリックし、パイプラインへのリンクをクリックしてから、タスクをクリックし、ログに記録されたデータを確認します。例：
エラーが発生した場合は、問題のトラブルシューティングを行い、パイプラインを再度実行します。
たとえば、基本イメージのファイルやモジュールが欠落している場合は、そのファイルが含まれている基本イメージを別途作成する必要があります。次に、Docker ファイルを指定し、パイプラインを介してイメージをプッシュします。

結果

完了です。 Code Streamをスラックインスタンスに接続してメッセージをスラックチャネルにポストするカスタム統合スクリプトを作成しました。

次のタスク

引き続きカスタム統合を作成します。パイプラインでカスタムタスクを使用するためのもので、 Code Streamの機能を拡張してソフトウェアリリースライフサイクルを自動化できます。