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 のランタイムを使用して、コンテナ イメージを生成します。

手順

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

    Code Streamがコードを実行するタスク ランタイム環境。次のいずれかの文字列を使用することができ、大文字と小文字は区別しません。

    • nodejs
    • python2
    • python3
    • shell

    何も指定しなかった場合は、shell がデフォルトとして使用されます。

    code カスタム タスクの一部として実行するカスタム ビジネス ロジック。
    inputProperties カスタム タスク構成の一部としてキャプチャする入力プロパティの配列。これらのプロパティは、通常はコード内で使用されます。
    outputProperties カスタム タスクからエクスポートしてパイプラインに伝達できる出力プロパティの配列。
  2. スクリプトで入力プロパティを宣言するときには、有効なデータ タイプおよびメタ データを使用します。
    入力プロパティは、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
    
  3. スクリプトで出力プロパティを宣言します。
    出力プロパティはスクリプトのビジネス ロジック code:セクションからキャプチャされるため、ここに出力のコンテキストを宣言します。
    パイプラインの実行時に、タスク出力の応答コードを入力できます。たとえば、 200 です。
    Code Stream[outputProperty] ごとにサポートされるキー。
    key 説明
    type 現在は、単一値 label が含まれています。
    name カスタム統合 YAML のコード ブロックによって送信されるキー。
    title [outputProperty] を表示するユーザー インターフェイスのラベル。
    例:
    outputProperties:
      - name: statusCode
        type: label
        title: Status Code
  4. カスタム スクリプトの入力および出力を操作するには、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
    
  5. 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();
    
  6. カスタム統合スクリプトをバージョン化してリリースする前に、Python または Node.js のコンテキスト ファイルをダウンロードし、スクリプトに含まれているビジネス ロジックをテストします。
    1. キャンバスの上部にポインタを置き、コンテキスト ファイル ボタンをクリックします。たとえば、スクリプトが Python に含まれている場合は、[CONTEXT.PY] をクリックします。
    2. ファイルを変更して保存します。
    3. 開発システムで、コンテキスト ファイルを利用してカスタム スクリプトを実行し、テストします。
  7. カスタム統合スクリプトにバージョンを適用します。
    1. [バージョン] をクリックします。
    2. バージョン情報を入力します。
    3. [リリース バージョン] をクリックして、カスタム タスクでスクリプトを選択できるようにします。
    4. バージョンを作成するには、[作成] をクリックします。
      カスタム統合スクリプトをバージョン管理し、パイプラインのカスタム タスクでバージョンを選択します。
  8. (オプション) カスタム統合スクリプトのいずれかのリリース バージョンを最新として設定すると、パイプライン キャンバスでそのバージョンに [latest -->] ラベルが表示されるようになります。
    1. キャンバスの上部にポインタを置き、[バージョン履歴] をクリックします。
    2. 使用可能なアクションを表示するには、目的のバージョンの横向き省略記号をクリックし、[最新として設定] を選択します。
      注: [最新として設定] アクションでは、リリース バージョンのみが表示されます。
      カスタム統合スクリプトをバージョン管理してリリースした後、特定のバージョンを最新として設定すると、ユーザーがパイプラインでバージョンを選択するときに、どれが現在のバージョンであるかがわかるようになります。
    3. バージョンの選択を承認するには、[最新として設定] をクリックします。
    4. [バージョン履歴] を終了してスクリプト エディタ キャンバスに戻るには、戻る矢印をクリックします。
  9. スクリプトを保存するには、[保存] をクリックします。
    スクリプトを YAML ファイルとしてエクスポートして別の Code Streamインスタンスで使用するには、カスタム統合カードで [アクション] > [エクスポート] の順にクリックし、エクスポートするバージョンを選択します。
  10. パイプラインで、ワークスペースを構成します。
    この例では、Docker ワークスペースを使用します。
    1. [ワークスペース] タブをクリックします。
    2. Docker ホストおよびビルダ イメージ URL を選択します。
      カスタム統合を作成する際は、ホスト、ビルダー イメージ URL、およびイメージ レジストリを含めます。
  11. パイプラインにカスタム タスクを追加して設定します。
    1. [モデル] タブをクリックします。
    2. タスクを追加し、タイプとして [カスタム] を選択し、適切な名前を入力します。
    3. カスタム統合スクリプトとバージョンを選択します。スクリプトのいずれかのバージョンが最新として設定されている場合、そのバージョンにはバージョン名の前に [latest -->] と表示されます。
    4. スラックにカスタム メッセージを表示するには、メッセージ テキストを入力します。
      入力したテキストでカスタム統合スクリプトの defaultValueがオーバーライドされます。
      カスタム タスクを追加するときは、カスタム スクリプトのバージョンを選択します。
  12. パイプラインを保存して有効にします。
    1. [保存] をクリックします。
    2. パイプライン カードで、[アクション] > [有効] の順にクリックします。
  13. パイプラインを実行します。
    1. [実行] をクリックします。
    2. パイプラインの実行状況を確認します。
    3. ステータス コード、応答コード、ステータス、および宣言出力が想定どおりであることを確認します。
      出力プロパティとして [statusCode] を定義しました。たとえば、 [statusCode]200 であれば、スラックのポストが正常に完了したことになり、 [responseCode]0 であれば、スクリプトがエラーなしで正常に完了したことになります。
    4. 実行ログで出力を確認するには、[実行] をクリックし、パイプラインへのリンクをクリックしてから、タスクをクリックし、ログに記録されたデータを確認します。例:
      パイプラインでカスタム タスクが実行された後、パイプラインの実行でカスタム統合のタスク出力を表示できます。
  14. エラーが発生した場合は、問題のトラブルシューティングを行い、パイプラインを再度実行します。
    たとえば、基本イメージのファイルやモジュールが欠落している場合は、そのファイルが含まれている基本イメージを別途作成する必要があります。次に、Docker ファイルを指定し、パイプラインを介してイメージをプッシュします。

結果

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

次のタスク

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