include로 추가된 구성을 위한 입력값 정의

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated
  • 이슈에서 GitLab 15.11의 베타 기능으로 소개되었습니다.
  • GitLab 16.6에서 일반적으로 사용 가능하게 되었습니다.

재사용되도록 설계된 CI/CD 구성 파일의 유연성을 높이기 위해 입력값을 사용하세요.

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

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

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

사양은 구성 파일의 맨 위에 헤더 섹션으로 선언되어야 합니다. 나머지 구성부분과는 ---로 구분하세요.

헤더 섹션 외부에서 값들을 대체하기 위해 보간 형식 $[[ inputs.input-id ]]를 사용하세요. 입력값은 구성을 가져올 때 평가 및 보간되지만, .gitlab-ci.yml 파일의 내용과 병합되기 전에 평가 및 보간됩니다.

예를 들어, 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(지정되지 않은 경우 기본값), 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 "웹사이트 스캔 중 -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]"
    - if [ $[[ inputs.export_results ]] ]; then echo "결과 내보내기"; fi

이 예에서: - job-prefix는 필수 문자열 입력값으로 정의되어야 합니다. - job-stage는 선택 사항입니다. 정의되지 않았을 때 값은 test가 됩니다. - environment는 정의된 옵션 중 하나와 일치해야 하는 필수 문자열 입력값입니다. - concurrency는 선택 사항의 숫자 입력값입니다. 지정되지 않았을 때 값은 1로 기본값을 갖습니다. - version은 지정된 정규 표현식과 일치해야 하는 필수 문자열 입력값입니다. - export_results는 선택 사항의 불리언 입력값입니다. 지정되지 않았을 때 값은 true로 기본값을 갖습니다.

여러 줄의 입력 문자열 값

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

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 포함된 구성의 spec:inputs:type이 boolean로 설정되어 있기 때문에 true 또는 false이어야 합니다. 기본값을 덮어씁니다.

여러 파일로 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

동일한 파일을 여러 번 포함

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

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

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

path/to/my-super-linter.yml의 구성은 각 포함될 때마다 고유한 이름을 가지도록 합니다: 

spec:
  inputs:
    type:
    lint-path:
---
"run-$[[ inputs.type ]]-lint":
  script: ./lint --$[[ inputs.type ]] --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에 5의 문자 오프셋과 8의 길이를 적용합니다.
  3. script의 출력은 echo my value가 될 것입니다.

미리 정의된 보간 함수

expand_vars

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

포함된 구성의 include 키워드와 함께 사용할 수 있는 변수 및 마스킹되지 않은 변수만 확장할 수 있습니다. 중첩된 변수 확장은 지원되지 않습니다.

예제: 

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

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

이 예에서, $MY_VAR가 (잡 로그에 노출된) 값 my value인 경우, 입력값은 test my value로 확장됩니다.

truncate

- GitLab 16.3에 도입되었습니다.

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

  • truncate(<offset>,<length>)
이름 타입 설명
offset 정수 오프셋으로 사용할 문자 수
length 정수 오프셋 이후 반환할 문자 수

예시: 

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

inputs.test의 값이 0123456789인 경우, 결과는 34567이 됩니다.

문제 해결

inputs를 사용할 때 YAML 구문 오류

CI/CD 변수 표현식은 rules:if에서 CI/CD 변수와 문자열을 비교하는 것을 요구하며, 그렇지 않을 경우 다양한 구문 오류가 발생할 수 있습니다.

구성에 입력값이 삽입된 후에도 표현식이 올바르게 형식화되어 있는지 확인해야 합니다. 이를 위해 추가적인 따옴표 문자 사용이 필요할 수 있습니다.

예를 들어: 

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

작업 이름:
  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.environment1 | expand_vars ]]" == "production"'

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