Parameter

パラメーターはジョブやコマンドなどに動的な値を渡す為に使えます。以下の3-4つの値を設定できます。

  1. description
  2. type
  3. default
  4. enum (typeenumの時に限る)

description

パラメーターの説明を書きます。この説明は Orb ドキュメントに使われます。

type

パラメーターの型を指定します。これには以下の

  1. boolean
  2. integer
  3. string
  4. enum
  5. executor
  6. steps
  7. env_var_name (環境変数)

boolean

真には、y yes true onが使えます。偽には、n no false offがあります。

integer

数値だけの値はintegerとして扱われます。

string

booleanintegerに含まれない値がこの型になります。ちなみにwhenでの判断時に、空文字列はfalse扱いです。

enum

渡せる値を羅列した値のどれかに制限したい時に使います。この型に限りenumキーも必須になります。

parameters:
  a:
    type: enum
    enum:
      - foo
      - bar
      - baz
      

executor

仕様するexecutorを指定します。これはexecutorsで定義されている名前でなければなりません。もし存在しない名前を渡すと「Cannot find a definition for executor named 渡した名前」のようなエラーになります。

これはある言語の複数バージョンでジョブを走らせたい時などに使えます。以下はechoというジョブを NodeJS が12の環境と10の環境で走らせる例です。エグゼキューターそのものにパラメーターがある場合、ワークフローbのようにエグゼキューター名はnameに置き、同じ階層にエグゼキューターのもつパラメーター値を置くことができます。

version: 2.1

executors:
  node12:
    parameters:
      text:
        type: string
        default: a
    docker:
      - image: circleci/node:12
    environment:
      TEXT: << parameters.text >>
  node10:
    parameters:
      text:
        type: string
    docker:
      - image: circleci/node:10
    environment:
      TEXT: << parameters.text >>

jobs:
  echo:
    parameters:
      e:
        type: executor
    executor: << parameters.e >>
    steps:
      - run: echo $TEXT

workflows:
  a:
    jobs:
      - echo:
          e: node12
  b:
    jobs:
      - echo:
          e:
            name: node10
            text: b

steps

個別にstepsを切り替えたい時などに使えます。渡せるのはjob.stepsと同じ構造のものです。パラメータで渡されたステップはstepsjob.stepsの中のsteps)に渡します。

version: 2.1

jobs:
  echo:
    parameters:
      s:
        type: steps
        default:
          - run: echo a
    docker:
      - image: alpine
    steps:
      - steps: << parameters.s >>

workflows:
  a:
    jobs:
      - echo
  b:
    jobs:
      - echo:
          s:
            - run: echo b

なお、stepsを使ったあとに書き直すなどしてsteps: echo ...などとしてしまうとパースエラーという分かりづらいエラーメッセージしか吐かなく、ハマりやすいので注意が要りそうです。

env_var_name

環境変数を渡す為に使います。渡されてた値を使う時は展開前のただの環境変数名が入っているだけなので、展開するには${ }で囲ってあげる必要があります。

この型は特に存在しない環境変数を指定したとしても問題ありません。以下は、

  • CIRCLE_BRANCH (ciがデフォルトで設定する環境変数)
  • PROJECT_ENV_VAR (設定ページで設定した環境変数)
  • JOB_ENV_VAR (ジョブで定義した環境変数)
  • UNDEFINED_ENV_VAR (存在しない環境変数)

echoった例ですが、それぞれ値があればちゃんと展開後の値が表示されました。

version: 2.1

jobs:
  echo:
    parameters:
      value:
        type: env_var_name
        default: CIRCLE_BRANCH
    docker:
      - image: alpine
    steps:
      - run: echo ${<< parameters.value >>}
    environment:
      JOB_ENV_VAR: JOB_ENV_VAR

workflows:
  a:
    jobs:
      - echo
  b:
    jobs:
      - echo:
          value: PROJECT_ENV_VAR
  c:
    jobs:
      - echo:
          value: JOB_ENV_VAR
  d:
    jobs:
      - echo:
          value: UNDEFINED_ENV_VAR