‘include’로 추가된 구성에 대한 입력 정의

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

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

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

spec:inputs를 사용하여 입력 매개변수 정의

spec:inputs를 사용하여 재사용 가능한 CI/CD 구성 파일에 채워넣을 수 있는 매개변수를 정의합니다. 그런 다음 include:inputs를 사용하여 프로젝트의 파이프라인에 구성을 추가하고 매개변수의 값을 설정합니다.

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

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

이 예에서 입력은 job-stageenvironment입니다. 그런 다음 .gitlab-ci.yml 파일에 이 구성을 추가하고 입력값을 설정할 수 있습니다:

include:
  - local: "custom_website_scan.yml"
    inputs:
      job-stage: "my-test-stage"
      environment: "my-environment"

스펙은 구성 파일의 맨 위에 선언되어야 하며, 다른 구성과 ---로 구분된 헤더 섹션에 있어야 합니다. 헤더 섹션 밖에 있는 $[[ inputs.input-id ]] 보간 형식을 사용하여 입력을 사용할 위치를 선언합니다.

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 포함된 구성의 spec:inputs:typeboolean으로 설정하려면 true 또는 false 중 하나여야 합니다. 기본값을 덮어씁니다.

다중 파일로 include:inputs 사용

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

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

자식 파이프라인으로 inputs 사용하기

만약 자식 파이프라인 구성 파일이 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 ]]

inputs에서 구성 재사용

inputs과 함께 구성을 재사용하려면 YAML 앵커를 사용할 수 있습니다.

예를 들어, rules 배열을 지원하는 여러 컴포넌트에서 동일한 rules 구성을 재사용하려면:

.my-job-rules: &my-job-rules
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

include:
  - component: $CI_SERVER_FQDN/project/path/component1@main
    inputs:
      job-rules: *my-job-rules
  - component: $CI_SERVER_FQDN/project/path/component2@main
    inputs:
      job-rules: *my-job-rules

!reference 태그는 inputs에서 사용할 수 없습니다만, 이슈 424481에서 이 기능을 추가하도록 제안되었습니다.

inputs 예시

needs와 함께 inputs 사용하기

복잡한 작업 의존성에 대해 배열 유형 입력을 사용하여 needs와 함께 사용할 수 있습니다.

예를 들어, component.yml이라는 파일에 다음과 같이 있는 경우:

spec:
  inputs:
    first_needs:
      type: array
    second_needs:
      type: array
---
test_job:
  script: echo "this job has needs"
  needs:
    - $[[ inputs.first_needs ]]
    - $[[ inputs.second_needs ]]

이 예에서의 입력은 first_needssecond_needs입니다. 모두 배열 유형 입력입니다. 그런 다음 .gitlab-ci.yml 파일에서 이 구성을 추가하고 입력값을 설정할 수 있습니다:

include:
  - local: "component.yml"
    inputs:
      first_needs:
        - build1
      second_needs:
        - build2

파이프라인을 시작할 때, test_jobneeds 배열에 있는 항목들이 이어져 다음과 같이 됩니다:

test_job:
  script: echo "this job has needs"
  needs:
    - build1
    - build2

포함될 때 needs를 확장할 수 있도록 함

포함된 작업에는 needs이 있을 수 있지만 spec:inputsneeds 배열에 추가적인 작업을 추가할 수도 있습니다.

예를 들어:

spec:
  inputs:
    test_job_needs:
      type: array
      default: []
---
build-job:
  script:
    - echo "내 빌드 작업"

test-job:
  script:
    - echo "내 테스트 작업"
  needs:
    - build-job
    - $[[ inputs.test_job_needs ]]

이 예제에서:

  • test-job 작업은 항상 build-job을 필요로 합니다.
  • 기본적으로 테스트 작업은 test_job_needs: 배열 입력이 기본적으로 비어 있기 때문에 다른 작업이 필요하지 않습니다.

구성에서 test-job을 다른 작업이 필요하도록 설정하려면 파일을 포함할 때 test_needs 입력에 추가하면 됩니다. 예를 들어:

include:
  - component: $CI_SERVER_FQDN/project/path/component@1.0.0
    inputs:
      test_job_needs: [my-other-job]

my-other-job:
  script:
    - echo "나는 구성의 '빌드 작업'도 이 작업이 필요합니다"

needs를 포함된 작업에 추가하기

이미 needs가 정의되지 않은 포함된 작업에 needs를 추가할 수 있습니다. 예를 들어, CI/CD 구성의 경우:

spec:
  inputs:
    test_job:
      default: test-job
---
build-job:
  script:
    - echo "내 빌드 작업"

"$[[ inputs.test_job ]]":
  script:
    - echo "내 테스트 작업"

이 예제에서 spec:inputs 섹션은 작업 이름을 사용자 정의할 수 있도록 합니다.

그런 다음 구성을 포함한 후, 작업을 추가로 확장하여 추가적인 needs 구성을 추가할 수 있습니다. 예를 들어:

include:
  - component: $CI_SERVER_FQDN/project/path/component@1.0.0
    inputs:
      test_job: my-test-job

my-test-job:
  needs: [my-other-job]

my-other-job:
  script:
    - echo "`my-test-job`이 이 작업이 필요합니다"

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

입력 값을 조작하기 위해 보편적으로 사용되는 함수를 보간 블록에 지정할 수 있습니다. 지원하는 형식은 다음과 같습니다:

$[[ 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. 그런 다음 truncate5의 문자 오프셋과 8의 길이로 test my value를 적용합니다.
  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: 구문이 보장됩니다. 표현식 내부와 외부 따옴표는 동일한 문자가 아니어야 합니다. 내부 따옴표로는 "을 외부 따옴표로는 '을 사용하거나, 그 반대로 사용할 수 있습니다. 반면, 작업 이름은 따옴표가 필요하지 않습니다.