구성에 추가된 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:typenumber로 설정된 포함된 구성에서 수치 값이어야 합니다. 기본값을 덮어씁니다.
version v1.3.2 명시적으로 정의되어야 하며, 포함된 구성의 spec:inputs:regex에서 지정된 정규식과 일치해야 합니다.
export_results false 명시되지 않아도 true 또는 false 여야 하며, 포함된 구성의 spec:inputs:typeboolean으로 설정됩니다. 기본값을 덮어씁니다.

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. 그런 다음 truncatetest 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: 구문이 됩니다. 식 내부와 외부의 따옴표는 동일한 문자여서는 안 됩니다. 안쪽 따옴표에 "를 사용하고, 바깥쪽에 '를 사용하거나 그 반대를 사용할 수 있습니다. 그 반면, 작업 이름에는 따옴표가 필요하지 않습니다.