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 파일의 내용과 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 (지정되지 않은 경우 기본값), 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입니다.

여러줄 입력 문자열 값

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

spec:
  inputs:
    closed_message:
      description: 이슈가 닫힐 때 알릴 메시지.
      default: '안녕 {{author}} :wave:,
        
        비활성화 된 이슈 정책에 따라 이제 닫힙니다.
        
        이 문제에 대해 추가 조치가 필요한 경우, 문제를 다시 열어주세요.'
---

include 사용 시 입력 값을 설정

  • GitLab 16.0에서 include:with를 include:inputs로 변경했습니다.

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 키워드로 사용할 수 있는 변수 및 마스킹되지 않은 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.environment1 | expand_vars ]]" == "production"'

이 예시에서 입력 블록과 전체 변수 표현식에 따옴표를 추가하여 입력값이 평가된 후에 유효한 if: 문법이 보장됩니다. 식 내부와 외부 따옴표는 동일한 문자여서는 안 됩니다. 내부 따옴표에는 "를 사용하고 외부 따옴표에는 ' 또는 그 반대를 사용할 수 있습니다. 배포용 환경 변수의 경우 따옴표가 필요하지 않습니다.