구성에 추가된 include용 입력 정의

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated Status: Beta

재사용을 목적으로 설계된 CI/CD 구성 파일의 유연성을 높이기 위해 입력을 사용하세요.

입력은 CI/CD 변수를 사용할 수 있지만, include 키워드의 변수 제한과 동일한 제한을 갖습니다.

spec:inputs로 입력 매개변수 정의하기

파이프라인에 include로 추가할 CI/CD 구성의 입력 매개변수를 정의하기 위해 spec:inputs를 사용하세요. 파이프라인을 빌드할 때 입력 값을 전달하려면 include:inputs를 사용하세요.

스펙은 구성 파일 상단에 제목 섹션에 선언되어야 합니다. 나머지 구성과는 ---로 구분하세요.

헤더 섹션 바깥에서 값을 교체하기 위해 보간 형식 $[[ inputs.input-id ]]을 사용하세요. 입력은 구성이 파이프라인 생성 중에 가져와질 때 평가 및 보간되지만, .gitlab-ci.yml 파일의 내용과 Merge되기 전에 이뤄집니다.

예를 들어, custom_website_scan.yml이라는 파일에서: 

spec:
  inputs:
    job-stage:
    environment:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

spec:inputs 사용 시:

  • 입력은 기본적으로 필수입니다.
  • 다음과 같은 유효성 오류가 반환됩니다:
    • 보간 블록이 1MB를 초과하는 문자열일 경우
    • 보간 블록 내 문자열이 1KB를 초과할 경우

또한, 다음을 사용하세요:

  • 입력이 명시되지 않은 경우 기본값을 정의하려면 spec:inputs:default를 사용하세요. 기본값이 명시되면 입력은 더 이상 필수가 아닙니다.
  • 특정 입력에 설명을 제공하려면 spec:inputs:description를 사용하세요. 설명은 입력에 영향을 주지는 않지만 입력 세부 정보나 예상값을 이해하는 데 도움이 될 수 있습니다.
  • 특정 입력에 대한 허용되는 값 디렉터리을 지정하려면 spec:inputs:options를 사용하세요.
  • 입력이 일치해야 하는 정규식을 지정하려면 spec:inputs:regex를 사용하세요.
  • 특정 입력 유형을 강제 적용하려면 spec:inputs:type을 사용하세요. 이는 string (명시되지 않은 경우 기본값), array, number, 또는 boolean이 될 수 있습니다.

여러 매개변수가 있는 입력 정의

하나의 CI/CD 구성 파일에 여러 입력을 정의할 수 있고, 각 입력은 여러 구성 매개변수를 가질 수 있습니다.

예를 들어, scan-website-job.yml이라는 파일에서: 

spec:
  inputs:
    job-prefix:     # 작업 이름의 접두어 (필수)
      description: "작업 이름의 접두어를 정의합니다"
    job-stage:      # 제공되지 않을 경우 기본값을 가지는 선택적 문자열 입력
      default: test
    environment:    # 정의된 옵션 중 하나와 일치해야 하는 필수 입력
      options: ['test', 'staging', 'production']
    concurrency:
      type: number  # 제공되지 않을 경우 기본값을 가지는 선택적 숫자 입력
      default: 1
    version:        # 특정 정규식과 일치해야 하는 필수 문자열 입력
      type: string
      regex: /^v\d\.\d+(\.\d+)$/
    export_results: # 제공되지 않을 경우 기본값을 가지는 선택적 부울 입력
      type: boolean
      default: true
---

"$[[ inputs.job-prefix ]]-scan-website":
  stage: $[[ inputs.job-stage ]]
  script:
    - echo "scanning website -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]"
    - if [ $[[ inputs.export_results ]] ]; then echo "export results"; fi

이 예시에서:

  • job-prefix는 필수 문자열 입력이며 정의되어야 합니다.
  • job-stage는 선택적입니다. 정의되지 않을 경우 값은 test가 됩니다.
  • environment는 정의된 옵션 중 하나와 일치해야 하는 필수 문자열 입력입니다.
  • concurrency는 선택적 숫자 입력입니다. 명시되지 않을 경우 기본값은 1이 됩니다.
  • version은 지정된 정규식과 일치해야 하는 필수 문자열 입력입니다.
  • export_results는 선택적 부울 입력입니다. 명시되지 않을 경우 기본값은 true가 됩니다.

입력 유형

선택적 spec:inputs:type 키워드를 사용하여 입력이 특정 유형을 사용해야 함을 명시할 수 있습니다.

입력 유형은 다음과 같습니다:

  • array
  • boolean
  • number
  • string (명시되지 않은 경우 기본값)

입력이 CI/CD 구성 내의 YAML 값을 전체로 대체하는 경우, 지정된 유형으로 구성에 보간되게 됩니다. 예를 들어: 

spec:
  inputs:
    array_input:
      type: array
    boolean_input:
      type: boolean
    number_input:
      type: number
    string_input:
      type: string
---

test_job:
  allow_failure: $[[ inputs.boolean_input ]]
  needs: $[[ inputs.array_input ]]
  parallel: $[[ inputs.number_input ]]
  script: $[[ inputs.string_input ]]

입력이 큰 문자열의 일부로 YAML 값 안에 삽입될 때는 항상 문자열로 보간됩니다. 예를 들어: 

spec:
  inputs:
    port:
      type: number
---

test_job:
  script: curl "https://gitlab.com:$[[ inputs.port ]]"

배열 유형

배열 유형의 항목 내용은 유효한 YAML 맵, 시퀀스 또는 스칼라일 수 있습니다. !reference와 같은 보다 복잡한 YAML 기능은 사용할 수 없습니다. 

spec:
  inputs:
    rules-config:
      type: array
      default:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
          when: manual
        - if: $CI_PIPELINE_SOURCE == "schedule"
---

test_job:
  rules: $[[ inputs.rules-config ]]
  script: ls

여러 줄 입력 문자열 값

입력은 다양한 값 유형을 지원합니다. 다음 형식을 사용하여 다중 문자열 값을 전달할 수 있습니다: 

spec:
  inputs:
    closed_message:
      description: "이슈가 닫힐 때 발송할 메시지입니다."
      default: '안녕하세요 {{author}} :wave:,
        
        비활성화된 이슈 정책에 따라, 이 이슈는 닫힙니다.
        
        이 문제가 추가 관심이 필요한 경우 이 이슈를 다시 열어주세요.'
---

include 사용 시 입력 값 설정하기

include:inputs를 사용하여 포함된 구성이 파이프라인에 추가될 때 매개변수 값 설정에 사용하세요.

예를 들어, 앞서 나온 예시에서 scan-website-job.yml을 포함시키려면: 

include:
  - local: 'scan-website-job.yml'
    inputs:
      job-prefix: 'some-service-'
      environment: 'staging'
      concurrency: 2
      version: 'v1.3.2'
      export_results: false

이 예시에서 포함된 구성의 입력은:

입력 값을 세부 정보
job-prefix some-service- 명시적으로 정의되어야 함.
job-stage test include:inputs에 정의되지 않아서, 값은 포함된 구성의 spec:inputs:default에서 가져옵니다.
environment staging 명시적으로 정의되어야 하며, 포함된 구성의 spec:inputs:options에서의 값 중 하나와 일치해야 합니다.
concurrency 2 spec:inputs:type이 number로 설정된 포함된 구성에서 수치 값이어야 합니다. 기본값을 덮어씁니다.
version v1.3.2 명시적으로 정의되어야 하며, 포함된 구성의 spec:inputs:regex에서 지정된 정규식과 일치해야 합니다.
export_results false 명시되지 않아도 true 또는 false 여야 하며, 포함된 구성의 spec:inputs:type이 boolean으로 설정됩니다. 기본값을 덮어씁니다.

include:inputs를 여러 파일에 사용

inputs는 각 포함된 파일마다 별도로 지정되어야 합니다. 예를 들어: 

include:
  - component: gitlab.com/the-namespace/the-project/the-component@1.0
    inputs:
      stage: my-stage
  - local: path/to/file.yml
    inputs:
      stage: my-stage

inputs를 자식 파이프라인에 사용

child pipelines에 입력을 전달할 수 있습니다. 단, 자식 파이프라인의 구성 파일이 spec:inputs를 사용하는 경우에만 가능합니다. 예를 들어: 

trigger-job:
  trigger:
    strategy: depend
    include:
      - project: my-group/my-project
        file: ".gitlab-ci.yml"
        inputs:
          job-name: "defined"
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

동일한 파일 여러 번 포함

동일한 파일을 다른 입력으로 여러 번 포함할 수 있습니다. 그러나 동일한 이름을 가진 여러 작업이 한 파이프라인에 추가된 경우, 추가 작업마다 이전 작업을 덮어씁니다. 중복 작업 이름을 방지하도록 구성해야 합니다.

예를 들어, 다른 입력으로 동일한 구성을 여러 번 포함하는 경우: 

include:
  - local: path/to/my-super-linter.yml
    inputs:
      linter: docs
      lint-path: "doc/"
  - local: path/to/my-super-linter.yml
    inputs:
      linter: yaml
      lint-path: "data/yaml/"

path/to/my-super-linter.yml의 구성은 포함될 때마다 작업이 고유한 이름을 갖도록 보장합니다: 

spec:
  inputs:
    linter:
    lint-path:
---
"run-$[[ inputs.linter ]]-lint":
  script: ./lint --$[[ inputs.linter ]] --path=$[[ inputs.lint-path ]]

입력 값 조작을 위한 함수 지정

입력 값을 조작하기 위해 보간 블록에 미리 정의된 함수를 지정할 수 있습니다. 지원되는 형식은 다음과 같습니다: 

$[[ input.input-id | <function1> | <function2> | ... <functionN> ]]
  • 미리 정의된 보간 함수만 허용됩니다.
  • 단일 보간 블록에 최대 3개의 함수를 지정할 수 있습니다.
  • 함수는 지정된 순서대로 실행됩니다. 
spec:
  inputs:
    test:
      default: 'test $MY_VAR'
---

test-job:
  script: echo $[[ inputs.test | expand_vars | truncate(5,8) ]]

이 예에서 입력이 기본 값 사용하고, $MY_VAR가 값 my value를 갖는 미마스킹된 프로젝트 변수인 경우:

  1. 먼저, 함수 expand_vars는 값을 test my value로 확장합니다.
  2. 그런 다음 truncate가 test my value에 대해 offset으로 5, length으로 8을 적용합니다.
  3. script의 출력은 echo my value가 됩니다.

미리 정의된 보간 함수

expand_vars

expand_vars를 사용하여 입력 값에서 CI/CD 변수를 확장합니다.

include 키워드를 사용할 수 있는 변수 및 마스킹되지 않은 CI/CD 변수만 확장할 수 있습니다. 중첩 변수 확장은 지원되지 않습니다.

예: 

spec:
  inputs:
    test:
      default: 'test $MY_VAR'
---

test-job:
  script: echo $[[ inputs.test | expand_vars ]]

이 예에서, $MY_VAR가 미마스킹된(작업 로그에 노출된) my value 값을 갖는 경우 입력은 test my value로 확장됩니다.

truncate

보간된 값을 줄이기 위해 truncate를 사용합니다. 예를 들어:

  • truncate(<offset>,<length>)
이름 유형 설명
offset 정수 오프셋하는 문자 수
length 정수 오프셋 이후 반환할 문자 수

예: 

$[[ inputs.test | truncate(3,5) ]]

inputs.test의 값이 0123456789인 경우, 출력은 34567이 됩니다.

문제 해결

inputs 사용 시 YAML 구문 오류

rules:if에서의 CI/CD 변수 표현식 은 CI/CD 변수와 문자열을 비교해야 하며, 그렇지 않으면 다양한 구문 오류가 반환될 수 있습니다.

입력 값이 구성에 삽입된 후에도 표현식이 올바르게 포맷되어 있도록 해야 합니다. 추가적인 따옴표 문자의 사용이 필요할 수 있습니다.

예를 들어: 

spec:
  inputs:
    branch:
      default: $CI_DEFAULT_BRANCH
---

job-name:
  rules:
    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch ]]

이 예에서:

  • include: inputs: branch: $CI_DEFAULT_BRANCH를 사용하는 것은 유효합니다. if: 절이 평가돼 if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH가 됩니다. 이는 유효한 변수 표현식입니다.
  • include: inputs: branch: main은 유효하지 않습니다. if: 절이 평가돼 if: $CI_COMMIT_REF_NAME == main가 되는데, 이는 main이 문자열이지만 따옴표로 감싸지 않았기 때문에 유효하지 않습니다.

대안으로 일부 변수 표현식 문제를 해결하기 위해 따옴표를 추가할 수 있습니다. 예를 들어: 

spec:
  inputs:
    environment:
      default: "$ENVIRONMENT"
---

$[[ inputs.environment | expand_vars ]] job:
  script: echo
  rules:
    - if: '"$[[ inputs.environment | expand_vars ]]" == "production"'

이 예에서 입력 블록과 전체 변수 표현식을 따옴표로 감싸면 입력이 평가된 후에 유효한 if: 구문이 됩니다. 식 내부와 외부의 따옴표는 동일한 문자여서는 안 됩니다. 안쪽 따옴표에 "를 사용하고, 바깥쪽에 '를 사용하거나 그 반대를 사용할 수 있습니다. 그 반면, 작업 이름에는 따옴표가 필요하지 않습니다.