‘include’로 추가된 구성에 대한 입력 정의
- 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 "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 ]]"
배열 유형
- ‘GitLab 16.11’에서 도입되었습니다.
배열 유형의 항목 내용은 유효한 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:with
를include:inputs
로 이름 바꿈 GitLab 16.0에서.
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 앵커를 사용할 수 있습니다.
예를 들어, 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_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
이 있을 수 있지만 spec:inputs
로 needs
배열에 추가적인 작업을 추가할 수도 있습니다.
예를 들어:
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
로 가정하면:
- 먼저
expand_vars
함수가 값을test my value
로 확장합니다. - 그런 다음
truncate
가5
의 문자 오프셋과8
의 길이로test my value
를 적용합니다. -
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:
구문이 보장됩니다. 표현식 내부와 외부 따옴표는 동일한 문자가 아니어야 합니다. 내부 따옴표로는 "
을 외부 따옴표로는 '
을 사용하거나, 그 반대로 사용할 수 있습니다. 반면, 작업 이름은 따옴표가 필요하지 않습니다.