ジョブテンプレート

ジョブテンプレートは、ユーザーがscrewdriver.yamlでジョブを設定する代わりに使用できる定義済みのコードのスニペットです。 ジョブテンプレートには、一連の定義済みのステップとDockerイメージが含まれます。

テンプレートを検索する

既に作成済みのテンプレートを見つけるには、GET メソッドで /templates APIエンドポイントにアクセスしてください。またこちらのパス<YOUR_UI_URL>/templatesにアクセスすることでテンプレートを確認できます。

テンプレートページの例: Templates

テンプレートを利用する

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

screwdriver.yamlの例:

jobs:
    main:
        requires: [~pr, ~commit]
        template: nodejs/test@1.0.4

バージョンは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テンプレートの例を参照してください。

例

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

jobs:
    main:
        requires: [~pr, ~commit]
        template: nodejs/test@stable

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

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

テンプレートのステップを上書き

ジョブは既存のステップをラップや置換をすることで、テンプレートのステップを上書きできます。

ラップする

ラップとは定義済みのステップの前、もしくは後に実行するコマンドを追加することを指します。 テンプレートで定義済みのステップをラップするには、pre もしくは post をステップ名の前に追加します。

例:

jobs:
    main:
        requires: [~pr, ~commit]
        template: nodejs/test@1.0.3
        steps:
            - preinstall: echo pre-install
            - postinstall: echo post-install

この例では、echo pre-install が テンプレートの install ステップの前に、echo post-install が install ステップの後に実行されます。

置換

テンプレートで定義済みのステップを置換するには、定義されているステップと同じ名前のステップを追加します。

例:

jobs:
    main:
        requires: [~pr, ~commit]
        template: nodejs/test@1.0.3
        steps:
            - install: echo skip installing

この例では、echo skip installing が install ステップで実行されます。

注意：ロックされたステップの置き換えはできません。

テンプレートで定義済みのイメージを置換することも出来ます。テンプレートのステップは、置換された後のイメージが持っていないコマンドや環境変数に依存しているかもしれないので、イメージの置換を行う際は注意してください。

例

jobs:
    main:
        requires: [~pr, ~commit]
        image: node:latest
        template: nodejs/test@1.0.3

sharedステップをマージ

テンプレートのステップを上書きする場合、ジョブは shared.steps または job.steps のいずれかのステップ定義を使用し、 jobs セクションで定義した steps が優先されます。これはテンプレートを使用しない場合のステップ定義の優先順位と同じです。この挙動はアノテーションの screwdriver.cd/mergeSharedSteps: true で変更することができます。テンプレートを使用している場合に true を設定すると、 shared セクションと job セクションのステップはマージされます。

例

次の例では、imageとstepsのマージされた構成を定義し、それをmainとmain2のジョブが使用します。

shared:
    image: node:lts
    template: nodejs/test
    steps:
        - init: npm install
        - pretest: npm lint
        - test: npm test
jobs:
    main:
        requires: [~pr, ~commit]
        image: node:lts
    main2:
        annotations:
            screwdriver.cd/mergeSharedSteps: true
        requires: [main]
        steps:
            - test: echo Skipping test

上記の例では、次のようになります。

jobs:
    main:
        requires: [~pr, ~commit]
        image: node:lts
        steps:
             - init: npm install
             - pretest: npm lint
             - test: npm test
    main2:
        annotations:
             screwdriver.cd/mergeSharedSteps: true
        requires: [main]
        image: node:lts
        steps:
             - init: npm install
             - pretest: npm lint
             - test: echo Skipping test

順序

設定でテンプレートを使用する場合、テンプレートで定義されたステップと自分の設定で定義されたステップを order フィールドで選択することができます。 このフィールドは、ステップ名の順序付き配列として定義されます。

orderを使用する際の注意点:

例 sd-template.yaml:

namespace: nodejs
name: publish
version: "2.0.1"
description: 'Publish an npm package'
maintainer: myname@foo.com
images:
  lts: node:lts
  latest: node:latest
config:
  image: stable
  steps:
    - install: npm install
    - publish: npm publish
    - coverage: coverage test.js

例 screwdriver.yaml:

jobs:
  main:
    requires: [~commit]
    image: stable
    template: nodejs/publish@2
    order: [clone, install, doesnotexist, test, publish, coverage]
    steps:
      - test: npm test
      - clone: git clone https://github.com/screwdriver-cd/toolbox.git ci
      - coverage: ./ci/coverage.sh

結果:

jobs:
  main:
    requires: [~commit]
    image: node:lts
    steps:
      - clone: git clone https://github.com/screwdriver-cd/toolbox.git ci
      - install: npm install
      - test: npm test
      - publish: npm publish
      - coverage: ./ci/coverage.sh  #  このステップは、ジョブによって上書きされました

テンプレートを作成する

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

テンプレートyamlを書く

テンプレートを作成するために、sd-template.yaml を含んだ新しいリポジトリを作成します。yamlには、テンプレートのネームスペース、名前、バージョン、説明、管理者のメールアドレス、使用するイメージと実行するステップの設定が必要です。ネームスペースが指定されていない場合、default のネームスペースが適用されます。オプションとして、imagesキーワードでサポートされてるイメージをラベル付きのリストで定義することもできます。基本的な例はscrewdriver-cd-test/template-example repoにあります。

sd-template.yamlの例:

namespace: myNamespace
name: template_name
version: '1.3'
description: template for testing
maintainer: foo@bar.com
images:
    lts-image: node:lts
    latest-image: node:latest
config:
    image: stable-image
    steps:
        - install: npm install
        - test: npm test
    environment:
        FOO: bar
    secrets:
        - NPM_TOKEN

テンプレートのイメージ

imagesに指定することで、サポートしているイメージをラベルやエイリアス付きで設定することができます。

例:

namespace: myNamespace
name: template_name
version: '1.3'
description: template for testing
maintainer: foo@bar.com
images:
    lts-image: node:lts
    latest-image: node:latest

以下のように、リストからエイリアスを使用することもできます。

jobs:
    main:
        template: myNamespace/template_name@1.3.0
        image: stable-image

サンプルリポジトリ: https://github.com/screwdriver-cd-test/template-images-example

テンプレートのステップ

ステップ名に、ラップする接頭語(preやpost)を使用しないでください。利用者がステップを変更したり補強する際に問題が発生します。例として、テンプレートが以下のステップを持っていたとします。

config:
    image: node:lts
    steps:
        - preinstall: echo Installing
        - install: npm install
        - test: npm test

そして、利用者が以下の追加のステップを利用しようとします。

jobs:
    main:
        template: myNamespace/template_name@1.3.0
        steps:
          - preinstall: echo foo

この場合、利用者がpreinstallを上書きしようとしているのか、installを補強しようとしているのかわからなくなります。

ロックされたテンプレートステップ

ステップに locked キーを追加することで、上書きできず、order を使用する際に必ず含まれるステップを指定することができます。 このキーにはブール値（true/false、デフォルトはfalse）を指定します。 このフラグは、このテンプレートを使用するすべてのテンプレートやジョブに適用されます。 ロックされたステップを持つテンプレートを使用するすべてのテンプレートは、同じロックされたステップを持つことになります。

config:
    image: node:lts
    steps:
        - preinstall: echo Installing
        - install: npm install
        - test:
            command: npm test
            locked: true

テンプレートのパラメーター

ステップ内で使用されるパラメーターを定義することができます。

例 sd-template.yaml:

namespace: myNamespace
name: favorites
version: '2.0.1'
description: template for testing parameters
maintainer: foo@bar.com
config:
  image: node:lts
  parameters:
    music:
      value: [ "country", "hip hop" ]
      description: "favorite music"
    color: [ "black", "white" ]
    sports:
      value: [ "baseball", "basketball" ]
  steps:
    - step_print_template_parameters: |
        echo music = $(meta get parameters.music)
        echo color = $(meta get parameters.color)
        echo sports = $(meta get parameters.sports)

サンプルリポジトリ: https://github.com/screwdriver-cd-test/template-parameters-example

これらのパラメーターはテンプレートを使う全てのジョブで継承されます。

例 screwdriver.yaml:

jobs:
  # パラメーター "music", "color", "sports" をテンプレートから継承します。
  main1:
    requires: [~pr, ~commit]
    template: favorites/myNamespace@2
  # パラメーター "music", "color", "sports" をテンプレートから継承します。
  main2:
    requires: [main1]
    template: favorites/myNamespace@2

これは下記の例と同じです。

jobs:
  main1:
    requires: [~pr, ~commit]
    parameters:
      music:
        value: [ "country", "hip hop" ]
        description: "favorite music"
      color: [ "black", "white" ]
      sports:
        value: [ "baseball", "basketball" ]
    steps:
      - step_print_template_parameters: |
          echo music = $(meta get parameters.music)
          echo color = $(meta get parameters.color)
          echo sports = $(meta get parameters.sports)
  main2:
    requires: [main1]
    parameters:
      music:
        value: [ "country", "hip hop" ]
        description: "favorite music"
      color: [ "black", "white" ]
      sports:
        value: [ "baseball", "basketball" ]
    steps:
      - step_print_template_parameters: |
          echo music = $(meta get parameters.music)
          echo color = $(meta get parameters.color)
          echo sports = $(meta get parameters.sports)

テンプレートで定義されたパラメーターは、パイプライン、ジョブの両方のスコープで上書きすることができ、ジョブのスコープがパイプラインのスコープより優先されます。

例 screwdriver.yaml

# パイプラインスコープのパラメーターは、ジョブスコープで上書きしない限り全てのジョブに適用されます。
# ジョブで使用されているテンプレート(favorites/myNamespace)のパラメーター "music" をパイプラインスコープのもので上書きします。
parameters:
  music: [jazz, rock]
jobs:
  # パラメーター "color" と "sports" をテンプレートから継承します。
  # テンプレートのパラメーター "music" はパイプラインスコープで上書きされるため、ジョブスコープでは継承されません。
  default_template_params:
    requires: [~pr, ~commit]
    template: favorites/myNamespace@2
  # パラメーター "sports" をテンプレートから継承します。
  # テンプレートのパラメーター "music" はパイプラインスコープで上書きされるため、ジョブスコープでは継承されません。
  # テンプレートのパラメーター "color" を上書きします。
  override_template_params:
    requires: default_template_params
    template: favorites/myNamespace@2
    parameters:
      color: [ red, blue ]

サンプルリポジトリ: https://github.com/screwdriver-cd-test/job-with-template-parameters-build-example

警告

テンプレート合成

sd-template.yamlファイルのconfigセクションでテンプレートを使用することもできます。

注意事項:

既存の例 sd-template.yaml:

namespace: nodejs
name: publish
version: "2.0.1"
description: 'Publish an npm package'
maintainer: myname@foo.com
images:
  lts: node:lts
  latest: node:latest
config:
  image: stable
  steps:
    - install: npm install
    - publish: npm publish
    - coverage: coverage test.js

例 sd-template.yaml:

namespace: d2lam
name: personal
version: "1.0.2"
description: 'Do some stuff'
maintainer: d2lam@foo.com
images:
  test: node:lts
config:
  template: nodejs/publish@2
  image: stable
  order: [clone, install, doesnotexist, test, publish, coverage]
  steps:
    - test: npm test
    - clone: git clone https://github.com/screwdriver-cd/toolbox.git ci
    - coverage: ./ci/coverage.sh

結果:

namespace: d2lam
name: personal
version: "1.0.2"
description: 'Do some stuff'
maintainer: d2lam@foo.com
images:
  lts: node:lts
  latest: node:latest
  test: node:lts
config:
  image: stable
  steps:
    - clone: git clone https://github.com/screwdriver-cd/toolbox.git ci
    - install: npm install
    - test: npm test
    - publish: npm publish
    - coverage: ./ci/coverage.sh  # このステップは、d2lam/personalテンプレートによって上書きされました

テンプレートリポジトリ用のscrewdriver.yamlを書く

テンプレートの検証

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

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

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

テンプレートのタグ付け

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

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

screwdriver.yamlの例:

shared:
    image: node:lts
jobs:
    main:
        requires: [~pr, ~commit]
        steps:
            - install: npm install screwdriver-template-main
            - validate: ./node_modules/.bin/template-validate
        environment:
            SD_TEMPLATE_PATH: ./path/to/template.yaml
    publish:
        requires: [main]
        steps:
            - install: npm install screwdriver-template-main
            - publish: ./node_modules/.bin/template-publish
            - autotag: ./node_modules/.bin/template-tag --name myNamespace/template_name --tag latest
            - tag: ./node_modules/.bin/template-tag --name myNamespace/template_name --version 1.3.0 --tag stable
        environment:
            SD_TEMPLATE_PATH: ./path/to/template.yaml
    remove:
        steps:
            - install: npm install screwdriver-template-main
            - remove: ./node_modules/.bin/template-remove --name myNamespace/template_name
    remove_tag:
        steps:
            - install: npm install screwdriver-template-main
            - remove_tag: ./node_modules/.bin/template-remove-tag --name myNamespace/template_name --tag stable

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

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

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

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

ビルドキャッシュを利用する

ビルドキャッシュを利用するには、store-cliコマンドをステップ内で使用します。例えば、node_modules/フォルダをキャッシュする場合、npm installを実行するステップの前にキャッシュをダウンロードするステップを設定し、その後キャッシュをアップロードする別のステップを指定します。teardown-プレフィックスを使用して、キャッシュをアップロードするステップをteardownに移動することもできます。

config:
    image: node:lts
    steps:
        - getcache: store-cli get node_modules/ --type=cache --scope=event || echo "Failed to fetch Cache"
        - install: npm install
        - teardown-putcache: store-cli set node_modules/ --type=cache --scope=event || echo "Failed to publish Cache"

テンプレートを削除する

screwdriver-template-main npm package を使う

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

UIを使う

または、テンプレートページのUIにあるゴミ箱アイコンをクリックすることで、テンプレートとそれに関連するすべてのタグおよびバージョンを削除できます。

注意: 誰がテンプレートを削除する権限を持っているか判断するのに必要なため、事前にテンプレートのパイプラインを削除しないでください。

Removing