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

カスタム スクリプトでは、ビルド、テスト、展開の各ツールと統合するために必要なことならほぼ何でもできます。たとえば、パイプラインのワークスペースを使用して、アプリケーションをビルドしてテストする CI タスクと、アプリケーションを展開する CD タスクをサポートできます。パイプラインの終了時にスラックにメッセージを送信するなど、さまざまなことができます。

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

カスタム タスクで、パイプラインによってスクリプトのバージョンを実行します。作成したスクリプトは、 Code Stream インスタンスに保存されます。

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

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

表 1. カスタム スクリプトを記述した後の操作
実行する操作 操作の詳細情報

パイプラインにカスタム タスクを追加します。

カスタム タスク:

  • パイプラインの他の CI タスクと同じコンテナで実行されます。
  • パイプラインがカスタム タスクを実行する前に、スクリプトでポピュレートする入出力変数を含めます。
  • 複数のデータ タイプとさまざまなタイプのメタ データをスクリプトに入力および出力として定義できます。

カスタム タスクでスクリプトを選択します。

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

パイプラインを保存し、有効にして実行します。

パイプラインを実行すると、カスタム タスクによって指定されたスクリプトのバージョンが呼び出され、そこでビジネス ロジックが実行されます。これにより、ビルド、テスト、展開の各ツールが 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 レンダリングする入力のタイプ:
    • テキスト
    • テキストエリア
    • 数値
    • チェックボックス
    • パスワード
    • 選択
    はい
    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 この入力プロパティの有効な最大値として機能する値を取得します。数値タイプの入力プロパティでのみサポートされます。 いいえ
    表 2. カスタム スクリプトでサポートされるデータ タイプとメタ データ
    サポートされるデータ タイプ 入力でサポートされるメタ データ
    • 文字列
    • テキスト
    • リスト:任意のタイプのリスト
    • マップ: 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. スクリプトを保存するには、[保存] をクリックします。
  9. パイプラインで、ワークスペースを設定します。
    1. [ワークスペース] タブをクリックします。
    2. Docker ホストおよびビルダ イメージ URL を選択します。
      カスタム統合の作成。
  10. パイプラインにカスタム タスクを追加して設定します。
    1. [モデル] タブをクリックします。
    2. タスクを追加し、タイプとして [カスタム] を選択し、適切な名前を入力します。
    3. カスタム統合スクリプトとバージョンを選択します。
    4. スラックにカスタム メッセージを表示するには、メッセージ テキストを入力します。
      入力したテキストでカスタム統合スクリプトの defaultValue がオーバーライドされます。例:
      パイプラインでのカスタム タスクの追加と設定。
  11. パイプラインを保存して有効にします。
    1. [保存] をクリックします。
    2. [パイプライン] タブで、[パイプラインを有効にする] をクリックして、円が右側になるようにします。
  12. パイプラインを実行します。
    1. [実行] をクリックします。
    2. パイプラインの実行状況を確認します。
    3. ステータス コード、応答コード、ステータス、および宣言出力が想定どおりであることを確認します。
      出力プロパティとして [statusCode] を定義しました。たとえば、 [statusCode]200 であれば、スラックのポストが正常に完了したことになり、 [responseCode]0 であれば、スクリプトがエラーなしで正常に完了したことになります。
    4. 実行ログで出力を確認するには、[実行] をクリックし、パイプラインへのリンクをクリックしてから、タスクをクリックし、ログに記録されたデータを確認します。例:
      カスタム統合のタスク出力の表示。
  13. エラーが発生した場合は、問題のトラブルシューティングを行い、パイプラインを再度実行します。
    たとえば、基本イメージのファイルやモジュールが欠落している場合は、そのファイルが含まれている基本イメージを別途作成する必要があります。次に、Docker ファイルを指定し、パイプラインを介してイメージをプッシュします。

結果

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

次のタスク

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