구성에 추가된 include
용 입력 정의
- GitLab 15.11에서 도입된 베타 기능입니다.
재사용을 목적으로 설계된 CI/CD 구성 파일의 유연성을 높이기 위해 입력을 사용하세요.
입력은 CI/CD 변수를 사용할 수 있지만, include
키워드의 변수 제한과 동일한 제한을 갖습니다.
spec:inputs
로 입력 매개변수 정의하기
파이프라인에 include
로 추가할 CI/CD 구성의 입력 매개변수를 정의하기 위해 spec:inputs
를 사용하세요. 파이프라인을 빌드할 때 입력 값을 전달하려면 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
(명시되지 않은 경우 기본값),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
사용 시 입력 값 설정하기
- 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
| 명시되지 않아도 true 또는 false 여야 하며, 포함된 구성의 spec:inputs:type 이 boolean 으로 설정됩니다. 기본값을 덮어씁니다.
|
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
inputs
를 자식 파이프라인에 사용
child pipelines에 입력을 전달할 수 있습니다.
단, 자식 파이프라인의 구성 파일이 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 ]]
입력 값 조작을 위한 함수 지정
- GitLab 16.3에서 도입됨.
입력 값을 조작하기 위해 보간 블록에 미리 정의된 함수를 지정할 수 있습니다. 지원되는 형식은 다음과 같습니다:
$[[ 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
가test my value
에 대해offset
으로5
,length
으로8
을 적용합니다. -
script
의 출력은echo my value
가 됩니다.
미리 정의된 보간 함수
expand_vars
- GitLab 16.5에서 도입됨.
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
- GitLab 16.3에서 도입됨.
보간된 값을 줄이기 위해 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:
구문이 됩니다.
식 내부와 외부의 따옴표는 동일한 문자여서는 안 됩니다. 안쪽 따옴표에 "
를 사용하고, 바깥쪽에 '
를 사용하거나 그 반대를 사용할 수 있습니다.
그 반면, 작업 이름에는 따옴표가 필요하지 않습니다.