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