パイプラインウィザード

パイプラインウィザードはVueのフロントエンドコンポーネントで、ユーザーが入力フィールドを使ってパイプラインを作成するのを支援します。入力フィールドの種類と最終的なパイプラインの形式は、YAML テンプレートで設定します。

パイプラインウィザードは、ユーザーフローを設定する単一のテンプレートファイルを想定しています。ウィザードはファイルの内容を問わないので、ウィザードを使用してさまざまなフローを表示できます。例えば、静的サイト用のテンプレートファイル、Dockerイメージ用のテンプレートファイル、モバイルアプリ用のテンプレートファイルなどです。第一段階として、これらのテンプレートはGitLabのソースコードの一部です。

テンプレートファイルは複数のステップを定義します。ユーザーに表示される最後のステップは常にコミットであり、テンプレート定義の一部ではありません。理想的なユーザーエクスペリエンスは2-3ステップで構成され、合計3-4ステップがユーザーに見えるようになります。

使用例

Vueコンポーネント

<!-- ~/my_feature/my_component.vue -->

<script>
  import PipelineWizard from '~/pipeline_wizard/pipeline_wizard.vue'
  import template from '~/pipeline_wizard/templates/my_template.yml';

  export default {
    name: "MyComponent",
    components: { PipelineWizard },
    data() {
      return { template }
    },
    methods: {
      onDone() {
        // redirect
      }
     }
  }
</script>

<template>
  <pipeline-wizard :template="template"
                   project-path="foo/bar"
                   default-branch="main"
                   @done="onDone" />
</template>

テンプレート

# ~/pipeline_wizard/templates/my_template.yml
id: gitlab/my-template
title: Set up my specific tech pipeline
description: Here's two or three introductory sentences that help the user understand what this wizard is going to set up.
steps:
  # Step 1
  - inputs:
      # First input widget
      - label: Select your build image
        description: A Docker image that we can use to build your image
        placeholder: node:lts
        widget: text
        target: $BUILD_IMAGE
        required: true
        pattern: "^(?:(?=[^:\/]{1,253})(?!-)[a-zA-Z0-9-]{1,63}(?<!-)(?:\.(?!-)[a-zA-Z0-9-]{1,63}(?<!-))*(?::[0-9]{1,5})?\/)?((?![._-])(?:[a-z0-9._-]*)(?<![._-])(?:\/(?![._-])[a-z0-9._-]*(?<![._-]))*)(?::(?![.-])[a-zA-Z0-9_.-]{1,128})?$"
        invalid-feedback: Please enter a valid docker image

      # Second input widget
      - label: Installation Steps
        description: "Enter the steps that need to run to set up a local build
          environment, for example installing dependencies."
        placeholder: npm ci
        widget: list
        target: $INSTALLATION_STEPS

    # This is the template to copy to the final pipeline file and updated with
    # the values input by the user. Comments are copied as-is.
    template:
      my-job:
        # The Docker image that will be used to build your app
        image: $BUILD_IMAGE

        before_script: $INSTALLATION_STEPS

        artifacts:
          paths:
            - foo

  # Step 2
  - inputs:
      # This is the only input widget for this step
      - label: Installation Steps
        description: "Enter the steps that need to run to set up a local build
          environment, for example installing dependencies."
        placeholder: npm ci
        widget: list
        target: $INSTALLATION_STEPS

    template:
      # Functions that should be executed before the build script runs
      before_script: $INSTALLATION_STEPS

結果

  1. Step 1
  2. Step 2
  3. Step 3

コミットステップ

ウィザードの最後のステップは常にコミットステップです。ユーザーは新しく作成したファイルをウィザードのpropsで定義されたリポジトリにコミットすることができます。ユーザーはコミット先のブランチを変更することができます。将来的には、ここから MR を作成する機能を追加する予定です。

コンポーネントAPIリファレンス

プロップス

  • template (必須):解析されていない文字列としてのテンプレートの内容。詳しくはテンプレートファイルの場所を参照してください。
  • project-path (必須):最終ファイルをコミットするプロジェクトのフルパス。
  • default-branch (必須):コミットステップであらかじめ選択されているブランチ。これはユーザーによって変更することができます。
  • default-filename (オプション、デフォルト:.gitlab-ci.yml):ファイルに使用するファイル名。これはテンプレートファイルで上書きできます。

イベント

  • done - ファイルがコミットされた後に発行されます。ユーザーをパイプラインにリダイレクトするときなどに使用します。

テンプレートファイルの場所

テンプレートファイルは通常YAMLファイルとして~/pipeline_wizard/templates/ に保存されます。

PipelineWizard コンポーネントはtemplate プロパティが解析されていないStringとして期待し、Webpack は上記のフォルダから.yml ファイルを文字列として読み込むように設定されています。別の場所からファイルを読み込む必要がある場合は、WebpackがそれをObjectとしてパースしないことを確認してください。

テンプレートリファレンス

テンプレート

テンプレート・ファイルのルート要素では、以下のプロパティを定義できます:

名前必須種類説明
id {チェックサークル}はい文字列です。一意のテンプレートID。この ID は名前空間パターンに従う必要があり、区切り文字としてフォワードスラッシュ/ を使用します。GitLab のソースコードにコミットしたテンプレートは、常にgitlab で始まる必要があります。例えばgitlab/my-template
title {チェックサークル}はい文字列です。ユーザーに表示されるページタイトル。ウィザードの上のh1 見出しになります。
description {チェックサークル}はい文字列です。ユーザーに表示されるページの説明。
filename {点線円}いいえ文字列です。生成されるファイルの名前。デフォルトは.gitlab-ci.yml です。
steps {チェックサークル}はいリスト ステップ定義のリスト。

step リファレンス

ステップは、マルチステップ(またはページ)プロセスの1ページを構成します。最終的な.gitlab-ci.yml の一部を構成する、1 つ以上の関連する入力フィールドで構成されます。

ステップには2つのプロパティがあります:

名前必須種類説明
template {チェックサークル}はい地図最終的な.gitlab-ci.yml にディープマージする生の YAML。このテンプレートセクションは入力フィールドの値に置き換えられる$ 記号で示される変数を含むことができます。
inputs {チェックサークル}はいリスト 入力定義のリスト。

input リファレンス

各ステップには、1つ以上のinputs を含めることができます。理想的なユーザーエクスペリエンスのためには、3つ以上含めるべきではありません。

入力のルックアンドフィールと生成される YAML タイプ (文字列、リストなど) はwidget に依存します。widget: text はテキスト入力を表示し、ユーザーの入力を文字列としてテンプレートに挿入します。widget: list は1つもしくは複数の入力フィールドを表示し、リストを挿入します。

すべてのinputs は、labelwidget、そしてオプションでtargetを持たなければなりませんが、ほとんどのプロパティは、使用されるウィジェットに依存します:

名前必須種類説明
label {チェックサークル}はい文字列です。入力フィールドのラベル。
widget {チェックサークル}はい文字列です。この入力に使用するウィジェットのタイプ。
target {点線円}いいえ文字列です。入力フィールドの値に置き換えられるべき、ステップのテンプレート内部の変数名。例えば、$FOO

ウィジェット

テキスト

widget: text として使います。これは YAML ファイルにstring を挿入します。

名前必須種類説明
label {チェックサークル}はい文字列です。入力フィールドのラベル。
description {点線円}いいえ文字列です。入力フィールドに関するヘルプテキスト。
required {点線円}いいえboolean次のステップに進む前に、ユーザーが値を提供しなければならないかどうか。定義されていない場合は、false
placeholder {点線円}いいえ文字列です。入力フィールドのプレースホルダ。
pattern {点線円}いいえ文字列です。ユーザーの入力が次のステップに進む前にマッチしなければならない正規表現。
invalidFeedback {点線円}いいえ文字列です。パターンバリデーションが失敗した場合に表示されるヘルプテキスト。
default {点線円}いいえ文字列です。フィールドのデフォルト値。
id {点線円}いいえ文字列です。入力フィールドIDは通常自動生成されますが、このプロパティを指定することで上書きすることができます。

リスト

widget: list として使います。これは YAML ファイルにlist を挿入します。

名前必須種類説明
label {チェックサークル}はい文字列です。入力フィールドのラベル。
description {点線円}いいえ文字列です。入力フィールドに関するヘルプテキスト。
required {点線円}いいえboolean次のステップに進む前に、ユーザーが値を提供しなければならないかどうか。定義されていない場合は、false
placeholder {点線円}いいえ文字列です。入力フィールドのプレースホルダ。
pattern {点線円}いいえ文字列です。ユーザーの入力が次のステップに進む前にマッチしなければならない正規表現。
invalidFeedback {点線円}いいえ文字列です。パターンバリデーションが失敗した場合に表示されるヘルプテキスト。
default {点線円}いいえリストリストのデフォルト値
id {点線円}いいえ文字列です。入力フィールドIDは通常自動生成されますが、このプロパティを指定することで上書きすることができます。

チェックリスト

widget: checklist として使用します。これは、次のステップに進む前にチェックする必要があるチェックボックスのリストを挿入します。

名前必須種類説明
title {点線円}いいえ文字列です。チェックリスト項目の上のタイトル。
items {点線円}いいえリストチェックが必要な項目のリスト。各項目は1つのチェックボックスに対応し、文字列またはチェックリスト項目を指定できます。
チェックリスト項目
名前必須種類説明
text {チェックサークル}はい文字列です。チェックリスト項目の上のタイトル。
help {点線円}いいえ文字列です。項目を説明するヘルプテキスト。
id {点線円}いいえ文字列です。入力フィールドIDは通常自動生成されますが、このプロパティを指定することで上書きすることができます。