CI/CD 입력값을 사용하여 CI/CD 구성의 유연성을 높이세요. 입력값과 CI/CD 변수는 비슷한 방식으로 사용할 수 있지만 각각 다른 장점이 있습니다:

• 입력값은 파이프라인 생성 시 기본 제공 유효성 검사와 함께 재사용 가능한 템플릿에 대한 타입이 지정된 파라미터를 제공합니다. 파이프라인이 실행될 때 특정 값을 정의하려면 CI/CD 변수 대신 입력값을 사용하세요.
• CI/CD 변수는 여러 수준에서 정의할 수 있는 유연한 값을 제공하지만, 파이프라인 실행 중에 수정할 수 있습니다. 작업의 런타임 환경에서 접근해야 하는 값에는 변수를 사용하세요. 동적 파이프라인 구성을 위해 rules와 함께 사전 정의된 변수를 사용할 수도 있습니다.

CI/CD 입력값과 변수 비교#

입력값:

• 목적: CI 구성(템플릿, 컴포넌트 또는 .gitlab-ci.yml)에 정의되고 파이프라인이 트리거될 때 값이 할당되어 소비자가 재사용 가능한 CI 구성을 사용자 정의할 수 있습니다.
• 수정: 파이프라인 초기화 시 전달되면 입력값은 CI/CD 구성에 보간되고 전체 파이프라인 실행 동안 고정됩니다.
• 범위: .gitlab-ci.yml 또는 include되는 파일에서 정의된 파일에서만 사용 가능합니다. include:inputs를 사용하여 다른 파일에 명시적으로 전달하거나 trigger:inputs를 사용하여 파이프라인에 전달할 수 있습니다.
• 유효성 검사: 타입 확인, 정규 표현식 패턴, 사전 정의된 옵션 목록 및 사용자를 위한 유용한 설명을 포함한 강력한 유효성 검사 기능을 제공합니다.

CI/CD 변수:

• 목적: 작업 실행 중에 환경 변수로 설정하고 파이프라인의 다양한 부분에서 작업 간 데이터를 전달하는 데 사용할 수 있는 값입니다.
• 수정: dotenv 아티팩트, 조건부 규칙 또는 작업 스크립트에서 직접 파이프라인 실행 중에 동적으로 생성하거나 수정할 수 있습니다.
• 범위: 전역(모든 작업에 영향), 작업 수준(특정 작업에만 영향) 또는 GitLab UI를 통해 전체 프로젝트 또는 그룹에 대해 정의할 수 있습니다.
• 유효성 검사: 최소한의 기본 제공 유효성 검사가 있는 단순 키-값 쌍이지만, GitLab UI에서 프로젝트 변수에 대한 일부 제어를 추가할 수 있습니다.

spec:inputs로 입력 파라미터 정의#

CI/CD 구성 헤더에서 spec:inputs를 사용하여 구성 파일에 전달할 수 있는 입력 파라미터를 정의하세요.

헤더 섹션 외부에서 $[[ inputs.input-id ]] 보간 형식을 사용하여 입력값을 사용할 위치를 선언하세요.

예를 들어:

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

이 예시에서 입력값은 job-stage와 environment입니다.

입력값은 spec 섹션이 있는 파일에서만 사용할 수 있습니다. include로 추가된 다른 파일의 입력값을 사용하려면 포함된 파일에 명시적으로 전달하세요.

spec:inputs를 사용할 때:

• default가 지정되지 않으면 입력값은 필수입니다.
• 입력값은 파이프라인 생성 중 구성을 가져올 때 평가되고 채워집니다.
• 입력값을 포함하는 문자열은 1MB 미만이어야 합니다.
• 입력값 내부의 문자열은 1KB 미만이어야 합니다.
• 입력값은 CI/CD 변수를 사용할 수 있지만, include 키워드와 동일한 변수 제한이 있습니다.
• spec:inputs를 정의하는 파일에 작업 정의도 포함된 경우 헤더 뒤에 YAML 문서 구분자(---)를 추가하세요.

그런 다음 다음과 같이 할 때 입력값에 대한 값을 설정합니다:

• 이 구성 파일을 사용하여 새 파이프라인을 실행할 때. include 이외의 방법으로 새 파이프라인을 구성하기 위해 입력값을 사용할 때는 항상 기본값을 설정해야 합니다. 그렇지 않으면 다음을 포함하여 새 파이프라인이 자동으로 트리거되는 경우 파이프라인이 시작되지 않을 수 있습니다:
  • 머지 리퀘스트 파이프라인
  • 브랜치 파이프라인
  • 태그 파이프라인
• 파이프라인에 구성을 포함할 때. 필수 입력값은 include:inputs 섹션에 추가되어야 하며, 구성이 포함될 때마다 사용됩니다.

입력 구성#

입력값을 구성하려면 다음을 사용하세요:

• 지정되지 않은 경우 입력값의 기본값을 정의하려면 spec:inputs:default. 기본값을 지정하면 입력값은 더 이상 필수가 아닙니다.
• 특정 입력값에 대한 설명을 제공하려면 spec:inputs:description. 설명은 입력값에 영향을 미치지 않지만, 사람들이 입력 세부 정보나 예상 값을 이해하는 데 도움이 될 수 있습니다.
• 입력값에 대해 허용된 값 목록을 지정하려면 spec:inputs:options.
• 입력값이 일치해야 하는 정규 표현식을 지정하려면 spec:inputs:regex.
• 특정 입력 타입을 강제하려면 spec:inputs:type. 타입은 string (지정되지 않은 경우 기본값), array, number 또는 boolean일 수 있습니다.
• 다른 입력값의 값을 기반으로 조건부 options 및 default 값을 정의하려면 spec:inputs:rules.

CI/CD 구성 파일당 여러 입력값을 정의할 수 있으며, 각 입력값은 여러 구성 파라미터를 가질 수 있습니다.

예를 들어 scan-website-job.yml이라는 파일에서:

spec:
  inputs:
    job-prefix:     # Mandatory string input
      description: "Define a prefix for the job name"
    job-stage:      # Optional string input with a default value when not provided
      default: test
    environment:    # Mandatory input that must match one of the options
      options: ['test', 'staging', 'production']
    concurrency:
      type: number  # Optional numeric input with a default value when not provided
      default: 1
    version:        # Mandatory string input that must match the regular expression
      type: string
      regex: ^v\d\.\d+(\.\d+)$
    export_results: # Optional boolean input with a default value when not provided
      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 ]]"

Array 타입#

배열 타입의 항목 내용은 유효한 YAML 맵, 시퀀스 또는 스칼라가 될 수 있습니다. !reference와 같은 더 복잡한 YAML 기능은 사용할 수 없습니다. 배열 입력값의 값을 문자열에서 사용할 때 (예: script: 섹션의 echo "My rules: $[[ inputs.rules-config ]]"), 예상치 못한 결과가 발생할 수 있습니다. 배열 입력값은 문자열 표현으로 변환되는데, 이는 맵과 같은 복잡한 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

배열 입력값은 다음을 위해 입력값을 수동으로 전달할 때 JSON 형식으로 지정해야 합니다 (예: ["array-input-1", "array-input-2"]):

• 수동으로 실행된 파이프라인.
• 파이프라인 트리거 API.
• 파이프라인 API.
• Git 푸시 옵션
• 파이프라인 스케줄

옵션이 있는 Array 입력값#

배열 입력값에 허용되는 값을 제한하기 위한 옵션 목록을 정의할 수 있습니다. 파이프라인을 수동으로 실행할 때 UI에 텍스트 필드 대신 다중 선택 드롭다운이 표시됩니다. 예를 들어:

spec:
  inputs:
    runner_tags:
      type: array
      default: ["docker"]
      options:
        - docker
        - linux
        - gpu
        - macos
---

test:
  script:
    - run_tests.sh
  tags: $[[ inputs.runner_tags ]]

배열 입력값의 값이 나열된 옵션과 일치하지 않으면 파이프라인 시작에 실패합니다.

개별 배열 요소 접근#

인덱스 번호와 함께 괄호 표기법을 사용하여 배열 입력값의 개별 요소에 접근하세요. 배열 항목은 YAML 배열에서 정의된 순서대로 양수로 인덱싱되며, [0] 인덱스 항목이 배열의 첫 번째 항목입니다.

예를 들어:

spec:
  inputs:
    supported_versions:
      type: array
      default:
        - '2.0'
        - '1.0'
        - '0.1'
---

job:
  script:
    # Outputs: 'Latest version is 2.0'
    - echo 'Latest version is $[[ inputs.supported_versions[0] ]]'

점 표기법과 배열 인덱싱을 연결하여 중첩된 값에 접근할 수 있습니다:

spec:
  inputs:
    servers:
      type: array
      default:
        - host: server1.example.com
          port: 8080
---

job:
  script:
    - curl "https://$[[ inputs.servers[0].host ]]:$[[ inputs.servers[0].port ]]"

다차원 배열의 경우 여러 인덱스를 연속으로 사용하세요. 예를 들어, 2차원 배열에 [0][1]을 사용할 수 있습니다:

spec:
  inputs:
    matrix:
      type: array
      default:
        - ['a', 'b']
        - ['c', 'd']
---

job:
  script:
    # Outputs: 'b'
    - echo $[[ inputs.matrix[0][1] ]]

세그먼트당 최대 5개의 인덱스를 연결할 수 있습니다. 예를 들어 arr[0][1][2][3][4].

멀티라인 입력 문자열 값#

입력값은 다양한 값 타입을 지원합니다. 다음 형식을 사용하여 멀티 문자열 값을 전달할 수 있습니다:

spec:
  inputs:
    closed_message:
      description: Message to announce when an issue is closed.
      default: 'Hi {{author}} :wave:,

        Based on the policy for inactive issues, this is now being closed.

        If this issue requires further attention, reopen this issue.'
---

spec:inputs:rules로 조건부 입력 옵션 정의#

spec:inputs:rules를 사용하여 다른 입력값의 값을 기반으로 입력값에 대한 다른 options 및 default 값을 정의하세요. 다른 입력값이 제공하는 컨텍스트에 따라 하나의 입력값이 서로 다른 허용값을 가져야 하는 경우 이 구성을 사용할 수 있습니다.

rules 목록의 각 규칙은 다음을 가질 수 있습니다:

• if: 이 규칙이 적용되는 시점을 결정하기 위해 하나 이상의 입력값의 값을 확인하는 표현식. $[[ inputs.input-id ]] 보간과 동일한 구문을 사용합니다.
• options: 이 규칙이 일치할 때 입력값에 허용된 값 목록.
• default: 이 규칙이 일치할 때 사용할 기본값.

규칙은 순서대로 평가됩니다. 일치하는 if 조건이 있는 첫 번째 규칙이 사용됩니다. if 조건이 없는 마지막 규칙은 다른 규칙이 일치하지 않을 때 폴백 역할을 합니다.

예를 들어, 클라우드 제공업체와 환경에 따라 달라지는 인스턴스 타입을 정의하려면:

spec:
  inputs:
    cloud_provider:
      options: ['aws', 'gcp', 'azure']
      default: 'aws'
      description: 'Cloud provider'

    environment:
      options: ['development', 'staging', 'production']
      default: 'development'
      description: 'Target environment'

    instance_type:
      description: 'VM instance type'
      rules:
        - if: $[[ inputs.cloud_provider ]] == 'aws' && $[[ inputs.environment ]] == 'development'
          options: ['t3.micro', 't3.small']
          default: 't3.micro'
        - if: $[[ inputs.cloud_provider ]] == 'aws' && $[[ inputs.environment ]] == 'production'
          options: ['t3.xlarge', 't3.2xlarge', 'm5.xlarge']
          default: 't3.xlarge'
        - if: $[[ inputs.cloud_provider ]] == 'gcp'
          options: ['e2-micro', 'e2-small', 'e2-standard-4']
          default: 'e2-micro'
        - if: $[[ inputs.cloud_provider ]] == 'azure'
          options: ['Standard_B1s', 'Standard_B2s', 'Standard_D2s_v3']
          default: 'Standard_B1s'
        - options: ['small', 'medium', 'large']  # Fallback for any other case
          default: 'small'
---

deploy:
  script: |
    echo "Deploying to $[[ inputs.cloud_provider ]]"
    echo "Environment: $[[ inputs.environment ]]"
    echo "Instance: $[[ inputs.instance_type ]]"

이 예시에서:

• cloud_provider가 aws이고 environment가 development이면 사용자는 t3.micro 또는 t3.small 인스턴스 타입 중에서 선택할 수 있으며, 기본값은 t3.micro입니다.
• cloud_provider가 aws이고 environment가 production이면 다른 인스턴스 타입(t3.xlarge, t3.2xlarge, m5.xlarge)을 사용할 수 있습니다.
• cloud_provider가 gcp이면 환경에 관계없이 GCP 특정 인스턴스 타입을 사용할 수 있습니다.
• 어떤 조건도 일치하지 않으면 폴백 규칙이 일반 크기 옵션을 제공합니다.

여러 조건을 일치시키기 위해 || (OR) 연산자를 사용할 수도 있습니다. 예를 들어:

spec:
  inputs:
    deployment_type:
      options: ['canary', 'blue-green', 'rolling', 'recreate']
      default: 'rolling'

    requires_approval:
      description: 'Whether deployment requires manual approval'
      rules:
        - if: $[[ inputs.deployment_type ]] == 'canary' || $[[ inputs.deployment_type ]] == 'blue-green'
          options: ['true']
          default: 'true'
        - options: ['true', 'false']
          default: 'false'
---

deploy:
  script: echo "Deploying with $[[ inputs.deployment_type ]] strategy"

이 예시에서 requires_approval 입력값은 deployment_type이 canary 또는 blue-green일 때 true로 설정됩니다. 그 외의 경우에는 기본값이 false이고 true 또는 false가 모두 허용 옵션입니다.

default: null로 사용자 입력 값 허용#

default: null과 options 없이 spec:inputs:rules를 사용하여 사용자가 입력값에 대한 자신의 값을 입력할 수 있도록 하세요. 이는 환경 이름이나 테스트 구성과 같은 워크플로우별 값에 유용합니다.

예를 들어:

spec:
  inputs:
    deployment_type:
      options: ['standard', 'custom']
      default: 'standard'

    custom_config:
      description: 'Custom configuration value'
      rules:
        - if: $[[ inputs.deployment_type ]] == 'custom'
          default: null
---

deploy:
  script: echo "Config: $[[ inputs.custom_config ]]"

이 예시에서 deployment_type이 custom이면 custom_config 입력값이 파이프라인 실행 페이지에 나열되고 사용자는 입력값에 대한 값을 입력해야 합니다.

spec:inputs:rules와 함께 불리언 입력값 사용#

규칙 조건에서 불리언 입력값을 사용할 수 있습니다. 불리언 값은 불리언 리터럴(true/false)을 사용하여 비교할 수 있습니다:

spec:
  inputs:
    publish:
      type: boolean
      default: true

    publish_stage:
      rules:
        - if: $[[ inputs.publish ]] == true
          default: 'publish'
        - if: $[[ inputs.publish ]] == false
          default: 'test'
---

job:
  stage: $[[ inputs.publish_stage ]]
  script: echo "Publishing is $[[ inputs.publish ]]"

이 예시에서 publish가 true이면 publish_stage는 기본값이 publish입니다. publish가 false이면 기본값이 test입니다.

입력값 설정#

파이프라인 구성에서 또는 파이프라인을 트리거할 때 입력값을 설정할 수 있습니다.

파이프라인이 시작된 후에는 사용된 입력값을 가져올 수 없습니다. 값을 노출해도 안전한 경우 나중에 참조할 수 있도록 작업 로그에 값을 출력하거나 아티팩트에 저장할 수 있습니다.

include로 추가된 구성의 경우#

구성이 파이프라인에 추가될 때 입력값의 값을 설정하려면 include:inputs를 사용하세요. 다음 경우를 포함합니다:

• CI/CD 컴포넌트
• include로 추가된 다른 모든 구성.

예를 들어 입력 구성 예시의 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

이 예시에서 포함된 구성에 대한 입력값은:

입력값은 입력값을 정의하는 spec 섹션과 동일한 파일에서만 사용 가능합니다. include로 추가된 파일은 다른 파일이나 포함하는 파일에 정의된 입력값에 접근할 수 없습니다. 포함된 파일의 값을 사용하려면 include:inputs로 명시적으로 전달하세요.

여러 include 항목의 경우#

각 include 항목에 대해 입력값을 별도로 지정해야 합니다. 예를 들어:

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

파이프라인의 경우#

입력값은 타입 확인, 유효성 검사 및 명확한 계약을 포함하여 변수에 비해 이점을 제공합니다. 예기치 않은 입력값은 거부됩니다. 파이프라인의 입력값은 기본 .gitlab-ci.yml 파일의 spec:inputs 헤더에 정의되어야 합니다. 포함된 파일에 정의된 입력값은 파이프라인 수준 구성에 사용할 수 없습니다.

파이프라인에 대한 입력값을 정의할 때 항상 기본값을 설정해야 합니다. 그렇지 않으면 새 파이프라인이 자동으로 트리거되는 경우 파이프라인이 시작되지 않을 수 있습니다. 예를 들어, 머지 리퀘스트 파이프라인은 머지 리퀘스트의 소스 브랜치 변경에 대해 트리거될 수 있습니다. 머지 리퀘스트 파이프라인에 대한 입력값을 수동으로 설정할 수 없으므로 입력값에 기본값이 없으면 파이프라인 생성이 실패합니다. 이는 브랜치 파이프라인, 태그 파이프라인 및 자동으로 트리거되는 다른 파이프라인에서도 발생할 수 있습니다.

다음을 사용하여 입력값 값을 설정할 수 있습니다:

• 다운스트림 파이프라인
• 수동으로 실행된 파이프라인.
• 파이프라인 트리거 API
• 파이프라인 API
• Git 푸시 옵션
• 파이프라인 스케줄
• trigger 키워드

파이프라인은 최대 20개의 입력값을 사용할 수 있습니다.

이 이슈에서 피드백을 환영합니다.

다운스트림 파이프라인의 구성 파일이 spec:inputs를 사용하는 경우 다운스트림 파이프라인에 입력값을 전달할 수 있습니다.

예를 들어 trigger:inputs를 사용하면:

trigger-job:
  trigger:
    strategy: mirror
    include:
      - local: path/to/child-pipeline.yml
        inputs:
          job-name: "defined"
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

trigger-job:
  trigger:
    strategy: mirror
    project: project-group/my-downstream-project
    inputs:
      job-name: "defined"
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

외부 파일에서 파이프라인 입력값 정의#

외부 파일에 파이프라인 입력 정의를 정의하고 spec:include를 사용하여 프로젝트의 파이프라인 구성에 포함시켜 여러 CI/CD 구성에서 재사용할 수 있습니다.

예를 들어 shared-inputs.yml이라는 파일에 입력 정의가 있는 파일을 만드세요:

inputs:
  environment:
    description: "Deployment environment"
    options: ['staging', 'production']
  region:
    default: 'us-east-1'

그런 다음 local을 사용하여 .gitlab-ci.yml에 외부 입력값을 포함시킬 수 있습니다:

spec:
  include:
    - local: /shared-inputs.yml
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]] in $[[ inputs.region ]]"

파일이 프로젝트 외부에 저장된 경우 다음을 사용할 수 있습니다:

• project: 다른 GitLab 프로젝트의 파일. 전체 프로젝트 경로를 사용하고 file로 파일 이름을 정의하세요. 선택적으로 파일을 가져올 ref를 정의할 수도 있습니다.
• remote: 다른 서버의 파일. 파일에 대한 전체 URL을 사용하세요.

여러 입력 파일을 동시에 포함할 수도 있습니다. 예를 들어:

spec:
  include:
    - local: /shared-inputs.yml
    - project: 'my-group/shared-configs'
      ref: main
      file: '/ci/common-inputs.yml'
    - remote: 'https://example.com/ci/shared-inputs.yml'
---

외부 파일에서 입력값 재정의#

입력 키는 모든 포함된 파일과 인라인 사양에서 고유해야 합니다. 여러 포함된 파일에서 동일한 키를 사용하여 입력값을 정의하거나, 포함된 파일과 .gitlab-ci.yml 구성의 inputs: 섹션 모두에서 정의하면 다음 오류가 반환됩니다:

Duplicate input keys found: environment. Input keys must be unique across all included files and inline specifications.

이 오류를 수정하려면 각 입력 키가 포함된 파일이나 인라인 inputs: 섹션 중 하나에만 정의되도록 하세요.

입력값을 조작하는 함수 지정#

보간 블록에서 사전 정의된 함수를 지정하여 입력값을 조작할 수 있습니다. 지원되는 형식은 다음과 같습니다:

$[[ 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#

입력값의 CI/CD 변수를 확장하려면 expand_vars를 사용하세요.

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>)

예:

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

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

posix_escape#

입력값에서 POSIX Bourne shell 제어 또는 메타 문자를 이스케이프하려면 posix_escape를 사용하세요. posix_escape는 입력값의 관련 문자 앞에 \를 삽입하여 문자를 이스케이프합니다.

예:

spec:
  inputs:
    test:
      default: |
        A string with single ' and double " quotes and   blanks
---

test-job:
  script: printf '%s\n' $[[ inputs.test | posix_escape ]]

이 예시에서 posix_escape는 쉘 제어 또는 메타데이터 문자가 될 수 있는 문자를 이스케이프합니다:

$ printf '%s\n' A\ string\ with\ single\ \'\ and\ double\ \"\ quotes\ and\ \ \ blanks
A string with single ' and double " quotes and   blanks

이스케이프된 입력값은 제공된 대로 특수 문자와 간격을 보존합니다.

posix_escape는 입력값을 정확히 보존하기 위해 최선을 다하지만 일부 문자 조합은 여전히 원치 않는 결과를 초래할 수 있습니다. posix_escape를 사용해도 다음이 가능합니다:

• 문자열에 포함된 쉘 코드가 실행될 수 있습니다.
• 단일 또는 이중 따옴표가 주변 인용부를 이스케이프하는 데 사용될 수 있습니다.
• 변수 참조가 보호된 변수에 접근하는 데 사용될 수 있습니다.
• 입력 또는 출력 리다이렉션이 로컬 파일을 읽거나 쓰는 데 사용될 수 있습니다.
• 이스케이프되지 않은 공백은 쉘에서 문자열을 여러 인수로 분할하는 데 사용됩니다.

보안 목적으로 입력값이 신뢰할 수 있는지 확인해야 합니다. 다음을 사용할 수 있습니다:

• 문제가 있는 문자를 포함할 수 없는 spec:input:type number 또는 boolean.
• 문제가 있는 입력값을 방지하는 spec:input:regex 키워드.
• 사전 정의된 입력 옵션 목록을 정의하는 spec:input:options 키워드.

posix_escape를 expand_vars와 함께 사용하는 경우 expand_vars를 먼저 설정해야 합니다. 그렇지 않으면 posix_escape가 변수의 $를 이스케이프하여 확장을 방지합니다. 예를 들어:

test-job:
  script: echo $[[ inputs.test | expand_vars | posix_escape ]]

문제 해결#

rules에서 inputs를 사용할 때 YAML 구문 오류#

입력값을 사용하여 rules:if 표현식을 수정하면 다양한 구문 오류 중 하나가 발생할 수 있습니다.

이러한 오류는 종종 CI/CD 변수 표현식에서 문자열이 처리되는 방식과 관련이 있습니다. rules:if의 표현식은 인용된 문자열(' 또는 ")이나 다른 변수와 비교되는 CI/CD 변수를 예상합니다. 파이프라인 런타임에 입력값이 rules 구성에 삽입될 때 결과값이 인용된 문자열이나 변수가 아닐 수 있어 오류가 발생합니다.

예를 들어, 포함할 구성에서:

spec:
  inputs:
    branch:
      default: $CI_DEFAULT_BRANCH
    branch2:
      default: $CI_DEFAULT_BRANCH
---

job-name:
  rules:
    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch ]]
    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch2 ]]

그런 다음 기본 구성 파일에서:

include:
  inputs:
    branch: $CI_DEFAULT_BRANCH  # Valid
    branch2: main               # Invalid

이 예시에서:

• branch: $CI_DEFAULT_BRANCH 사용은 유효합니다. if: 절은 if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH로 평가되는데, 이는 유효한 변수 표현식입니다. 변수는 인용할 필요가 없습니다.
• branch2: main 사용은 유효하지 않습니다. if: 절은 if: $CI_COMMIT_REF_NAME == main으로 평가되는데, main이 문자열이지만 인용되지 않아 유효하지 않습니다.

이 문제를 해결하려면 입력값이 구성에 삽입된 후 표현식이 적절하게 형식화되어 있는지 확인하세요. 추가 따옴표 문자가 필요할 수 있습니다. 예를 들어, 문자열 값을 사용하는 rules에 따옴표를 추가하세요:

rules:
  if: $CI_COMMIT_REF_NAME == "$[[ inputs.branch2 ]]"

expand_vars와 같은 보간 함수의 경우 전체 if: 표현식을 인용해야 할 수도 있습니다. 예를 들어:

spec:
  inputs:
    environment:
      default: "$ENVIRONMENT"
---

$[[ inputs.environment | expand_vars ]] job:
  script: echo
  rules:
    - if: '"$[[ inputs.environment | expand_vars ]]" == "production"'

이 예시에서 입력값과 전체 if: 표현식을 모두 인용하면 입력값이 평가된 후 유효한 구문이 보장됩니다. 따옴표가 중첩된 경우 내부 따옴표에는 "를 사용하고 외부 따옴표에는 '를 사용하거나 반대로 사용하세요.

작업 이름은 인용할 필요가 없습니다.