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-stage와 environment입니다. 그런 다음, .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 "웹사이트 스캔 중 -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: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 포함된 구성의 spec:inputs:type이 boolean으로 설정되어야 하며, 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 앵커를 사용할 수 있습니다.

예를 들어, inputs에서 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

inputs에서 !reference 태그를 사용할 수는 없지만, 문제 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_needs와 second_needs이며, 둘 다 배열 형식의 입력입니다.

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

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

파이프라인이 시작되면 test_job의 needs 배열 항목이 다음과 같이 연결됩니다:

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

포함된 작업에서 needs 확장 허용

포함된 작업에서 needs를 가질 수 있으며, 추가 작업을 needs 배열에 spec:inputs로 추가할 수 있습니다.

예를 들어:

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 "이 작업도 `build-job`에 필요하길 원해요"

needs가 없는 포함된 작업에 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. 다음으로, 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

truncate를 사용하여 보간된 값을 줄입니다. 예를 들어:

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

예시:

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

inputs.test의 값이 0123456789라면 출력은 34567입니다.

문제 해결

inputs 사용 시 YAML 구문 오류

rules:if에서의 CI/CD 변수 표현식은 CI/CD 변수를 문자열과 비교할 것으로 기대하므로,

a variety of syntax errors could be returned.

입력 값이 구성에 삽입된 후 표현식이 올바르게 형식이 유지되도록 해야 하며, 경우에 따라 추가 따옴표 문자가 필요할 수 있습니다.

예시:

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: 구문을 보장합니다. 표현식의 내부 및 외부 따옴표는 동일한 문자가 아니어야 합니다. 내부 따옴표에는 "를 사용하고 외부 따옴표에는 '를 사용하거나 그 반대로 할 수 있습니다. 다른 한편으로, 작업 이름은 따옴표를 사용할 필요가 없습니다.