パイプラインテンプレート

パイプラインテンプレートは、ユーザーがscrewdriver.yamlを定義するために使用できる定義済みの設定のスニペットです。パイプラインテンプレートには、ステップを持つ一連の定義済みジョブとDockerイメージが含まれています。

テンプレートを検索する

既に作成済みのテンプレートを見つけるには、GET メソッドで /pipeline/templates APIエンドポイントにアクセスしてください。

テンプレートの例

namespace: nodejs
name: test
version: '1.0.4'
description: An example pipeline template for nodejs
maintainer: foo@bar.com
config:
  shared:
    image: node:lts
  jobs:
    main:
      steps:
        - install: npm install
        - test: npm test
      secrets:
        - NPM_TOKEN

テンプレートを利用する

テンプレートを利用するためには、screwdriver.yamlのトップにtemplateを記述します。以下の例では、nodejs/test templateを使用しています。

Example screwdriver.yaml:

template: nodejs/test@1.0.4
shared:
  environment: 
    FOO: bar        

バージョンはsemver互換です。例えば上記のテンプレートではnodejs/test@1やnodejs/test@1.0と指定できます。

テンプレートにタグがある場合は、タグバージョンを使用してテンプレートのバージョンを参照することもできます。全てのバージョンとタグはテンプレート詳細ページの下部に表示されており、テンプレートの例ではlatestとstableのタグが登録されていることがわかります。

ほとんどのテンプレートは、最後に公開されたバージョンをlatestとしてタグ付けし、多くのテンプレートは自動テストや人手によるチェックによってstableタグに更新しています。これはフローティングタグであるため、ジョブで使用した場合にテンプレートが提供する振る舞いが突然変更される可能性があります。

テンプレートのバージョンが指定されていない場合は、最後に公開されたバージョンが使用されます。これは通常、latestタグを指定することと同義です。一般的にはlatestを暗黙的に使用するよりも、テンプレートのバージョンを明示する方が適切です。

テンプレートの予期しない変更を回避する最も信頼できる方法は、テンプレートの特定のバージョンを明示的に指定することです。例えば、nodejs/test@1.0.4は不変な特定のバージョンのテンプレートへの参照を表しています。nodejs/test@1.0などと記述すると、nodejs/test@1.0.5が利用可能となったときにそれを使用しますが、振る舞いが予期せず変更される可能性があります。

バージョンタグの意味

テンプレートのバージョンは様々な方法で参照でき、振る舞いを固定するか、テンプレート管理者による機能改善を自動的に取り込むかがユーザーのトレードオフとして現れます。上記の例はnodejs/testテンプレートの例を参照してください。

nodejs/test@latest - これは後方互換性のない変更や、メジャーバージョンの変更などにも関わらず、最後に公開されたテンプレートのバージョンを使用します。latestタグは主にテンプレートの管理者のみが使用すべきであり、本番や重要なビルドには適していない可能性があります。
nodejs/test@stable - これは管理者が一般的な使用に十分安定していると判断したバージョンのテンプレートを使用します。stableタグを利用しているユーザーに対して振る舞いの大幅な変更が現れる場合があります。stableタグの変更に後方互換性がない場合、テンプレート管理者はユーザーとコミュニケーションをとる必要があります。
nodejs/test@1 - これは2.0.0未満の最新バージョンのnodejs/testを使用します。本質的には指定されたメジャーバージョンを超えないlatestタグということです。
nodejs/test@1.0 - これは1.1.0未満の最新バージョンのnodejs/testを使用します。本質的には指定されたマイナーバージョンを超えないlatestタグということです。
nodejs/test@1.0.4 - これはパイプラインの振る舞いを固定する最も確実な方法であり、将来的なテンプレートの変更に対して影響を受けません。

例

このような設定があったとします。

template: nodejs/test@stable
shared: 
  environment:
    FOO: bar

Screwdriverはテンプレートの設定を読み込み、screwdriver.yamlは以下のようになります。

shared:
  environment:
    FOO: bar
jobs:
    main:
      image: node:lts
      requires: [~pr, ~commit]
      steps:
        - install: npm install
        - test: npm test
      secrets:
        - NPM_TOKEN

テンプレートを作成する

テンプレートの作成と利用は、Screwdriverのパイプラインから実行する必要があります。

テンプレートyamlを書く

テンプレートを作成するために、sd-template.yaml を含んだ新しいリポジトリを作成します。yamlには、テンプレートのネームスペース、名前、バージョン、説明、管理者のメールアドレス、ジョブの設定が必要です。基本的な例は screwdriver-cd-test/pipe;line-template-example repoにあります。

Example sd-template.yaml:

namespace: myNamespace
name: template_name
version: '1.3'
description: pipeline template for testing
maintainer: foo@bar.com
config:
  jobs:
    main:
      requires: [~pr, ~commit]
      steps:
        - install: npm install
        - test: npm test
      environment:
          FOO: bar
          TEST: data
      secrets:
          - NPM_TOKEN

テンプレートリポジトリ用のscrewdriveryamlを書く

テンプレートの検証

テンプレートを検証するために、screwdriver-template-main という npm モジュールにある pipeline-template-validate スクリプトを main ジョブで実行します。つまり、ビルドに利用するイメージは Node.js と NPM が正しくインストールされている必要があります。テンプレートをパブリッシュするために、同様のモジュールに含まれている pipeline-template-publish を別のジョブで実行します。

デフォルトでは、./sd-template.yaml が読み込まれます。しかし、SD_TEMPLATE_PATH という環境変数を利用することで、任意のパスを指定することができます。

また、<YOUR_UI_URL>/validatorにコピーペーストすることで、UIを通して sd-template.yaml と screwdriver.yaml を検証することができます。

テンプレートのタグ付け

screwdriver-template-main という npm パッケージに含まれる pipeline-template-tag スクリプトを実行することで、テンプレートの特定のバージョンに対してタグを指定することが可能です。この処理はタグ付けをしたいテンプレートを作成したパイプラインからのみ実行可能です。スクリプトの引数にはテンプレート名、ネームスペース、タグを渡す必要があります。引数で特定のバージョンを指定してタグを付けることも可能です。その場合バージョンは正確なものである必要があります(tagのステップを参照)。バージョンを引数から省略した場合は最新のバージョンに対してタグ付けされます。

タグを削除するには pipeline-template-remove-tag を実行します。引数としてテンプレート名とタグを渡す必要があります。

Example screwdriver.yaml:

shared:
    image: node:lts
jobs:
  main:
      requires: [~pr, ~commit]
      steps:
        - validate: npx -y -p screwdriver-template-main pipeline-template-validate
      environment:
        SD_TEMPLATE_PATH: ./path/to/template.yaml
  publish:
      requires: [main]
      steps:
        - publish: npx -y -p screwdriver-template-main pipeline-template-publish
        - tag: npx -y -p screwdriver-template-main pipeline-template-tag --namespace myNamespace --name template_name --version 1.3.0 --tag stable
      environment:
        SD_TEMPLATE_PATH: ./path/to/template.yaml
  remove:
      steps:
        - remove: npx -y -p screwdriver-template-main pipeline-template-remove --namespace myNamespace --name template_name
  remove_tag:
      steps:
        - remove_tag: npx -y -p screwdriver-template-main pipeline-template-remove-tag --namespace myNamespace --name template_name --tag stable

Screwdriverのパイプラインをテンプレートリポジトリで作成し、テンプレートのバリデートとパブリッシュを行うためにビルドを開始します。

Screwdriverのテンプレートを更新するには、ご利用のSCMリポジトリに変更を加え、パイプラインのビルドを再度実行します。

テンプレートをテストする

テンプレートをテストするために、テンプレートテストのサンプルのようにテンプレートを利用する別のパイプラインを作成することで、リモートテストを設定します。この例では、リモートトリガーを利用することでpublish_nodejs_templateが実行された後にパイプラインが実行されます。注意: イベント作成時にテンプレートが展開されるので、同じパイプラインでテンプレートをテストすることはできません。テンプレートの作成されたパイプライン内で使用しようとすると、古いバージョンのテンプレートが使用されます。

テンプレートを削除する

screwdriver-template-main npm package を使う

テンプレートを削除するためにpipeline-template-removeスクリプトを実行することができます。テンプレート名とネームスペースを引数に与える必要があります。