잡 입력값을 사용하여 개별 CI/CD 잡에 대한 타입이 지정되고 유효성 검사된 매개변수를 정의할 수 있으며, 잡을 수동으로 실행하거나 재시도할 때 재정의할 수 있습니다. CI/CD 변수와 달리 잡 입력값은 다음을 제공합니다:

• 타입 안전성: 입력값은 자동 유효성 검사와 함께 string, number, boolean 또는 array일 수 있습니다.
• 명시적 계약: 잡은 정의한 입력값만 허용합니다. 예상치 못한 입력값은 거부됩니다.
• 재정의 기능: 잡을 실행할 때 입력값을 설정하고, 잡을 재시도할 때 변경할 수 있습니다.

잡 동작을 제어하고 잡을 다시 실행할 때 조정이 필요할 수 있는 매개변수에 잡 입력값을 사용하세요. 예를 들어 배포 대상, 테스트 구성 또는 기능 플래그 등이 있습니다.

잡 입력값은 해당 입력값이 정의된 잡으로만 범위가 제한되며 포함된 파일이나 다른 잡에서는 접근할 수 없습니다. 여러 잡 또는 파일에서 구성을 공유해야 하는 경우 대신 CI/CD 구성 입력값을 사용하세요.

잡 입력값 비교#

CI/CD 파이프라인 구성 입력값과의 비교#

잡 입력값과 CI/CD 파이프라인 구성 입력값은 서로 다른 목적으로 사용됩니다:

환경 변수와의 비교#

잡 입력값은 잡이 생성될 때 잡 구성에 보간됩니다. 환경 변수가 아니므로 $INPUT_NAME 구문으로 접근할 수 없습니다. ${{ job.inputs.INPUT_NAME }} 구문을 사용하여 스크립트 및 기타 지원되는 키워드에서 직접 잡 입력값을 사용할 수 있습니다.

잡 입력값 정의 및 사용#

잡에서 inputs 키워드를 사용하여 입력 매개변수를 정의합니다. 각 입력에는 기본값이 있어야 합니다. ${{ job.inputs.INPUT_NAME }} Moa 표현식 구문으로 입력값을 참조합니다.

예시:

deploy_job:
  inputs:
    target_env:
      default: staging
      options: [staging, production]
    replicas:
      type: number
      default: 3
    debug_mode:
      type: boolean
      default: false
  script:
    - 'echo "Deploying to ${{ job.inputs.target_env }}"'
    - 'echo "Replicas - ${{ job.inputs.replicas }}"'
    - 'if [ "${{ job.inputs.debug_mode }}" == "true" ]; then set -x; fi'
    - ./deploy.sh

입력 구성#

다음 키워드로 입력값을 구성합니다:

• default: 잡 실행 시 사용되는 기본값. 모든 잡 입력값에는 기본값이 있어야 합니다.
• type: 선택 사항. 입력 유형. string (기본값), number, boolean 또는 array일 수 있습니다.
• description: 선택 사항. 입력의 목적에 대한 사람이 읽기 쉬운 설명.
• options: 선택 사항. 허용된 값의 목록. 입력값은 이 값 중 하나와 일치해야 합니다.
• regex: 선택 사항. 입력값이 일치해야 하는 정규식 패턴.

예시:

test_job:
  inputs:
    test_framework:
      default: rspec
      description: Testing framework to use
      options: [rspec, minitest, cucumber]
    parallel_count:
      type: number
      default: 5
      description: Number of parallel test jobs
    run_integration_tests:
      type: boolean
      default: false
      description: Whether to run integration tests
    test_tags:
      type: array
      default: [smoke, regression]
      description: Test tags to run
  script:
    - bundle exec ${{ job.inputs.test_framework }}
    - 'echo "Running ${{ job.inputs.parallel_count }} parallel jobs"'

잡 입력값은 잡이 생성될 때와 입력값이 재정의될 때 유효성 검사가 이루어집니다. 유효성 검사에 실패하면 명확한 오류 메시지와 함께 잡 시작이 실패합니다.

입력 유형#

잡 입력값은 다음 유형을 지원합니다:

• string (기본값): 텍스트 값, 예를 들어 "staging" 또는 "v1.2.3".
• number: 숫자 값, 예를 들어 5, 3.14 또는 -10.
• boolean: 부울 값, true 또는 false.
• array: 값의 목록, 예를 들어 [1, 2, 3] 또는 ["a", "b"].

API 또는 UI를 통해 입력값을 전달할 때 배열은 JSON 형식이어야 합니다. 예를 들어: ["value1", "value2"].

잡 입력값을 사용할 수 있는 위치#

단순 보간 또는 연산자 및 함수를 사용하는 더 복잡한 표현식을 사용할 수 있습니다. 전체 구문은 Moa 표현식 언어를 참조하세요.

잡 입력값은 다음 잡 키워드 및 해당 하위 키에서 사용할 수 있습니다:

• script, before_script, after_script
• artifacts
• cache
• image
• services

제한 사항#

잡 입력값은 파이프라인 구성이 생성될 때가 아니라 잡이 실행될 때 평가되는 ${{ job.inputs.INPUT_NAME }} 구문을 사용합니다. 파이프라인 생성 시에 평가되어야 하는 구성 부분에서는 잡 입력값을 사용할 수 없습니다. 예를 들어:

• 잡 이름
• stage 키워드
• rules 키워드
• include 키워드
• 위에 나열되지 않은 다른 잡 수준 키워드

파이프라인의 이러한 부분을 동적으로 구성하려면 대신 $[[ inputs.* ]] 구문과 함께 CI/CD 파이프라인 구성 입력값을 사용하세요.

입력값 제공#

다음 경우에 잡 입력값을 제공할 수 있습니다:

• 수동 잡 실행 시.
• 잡 완료 후 재시도 시.

입력값으로 수동 잡 실행#

입력값이 정의된 수동 잡을 실행하면 입력값을 지정할 수 있습니다.

특정 입력값으로 수동 잡을 실행하려면:

1. 파이프라인, 잡 또는 환경 보기로 이동합니다.
2. Run ([play])이 아닌 수동 잡의 이름을 선택합니다.
3. 양식에서 입력값을 지정합니다.
4. Run job을 선택합니다.

다른 입력값으로 잡 재시도#

입력값이 정의된 잡을 재시도하면 입력값을 업데이트할 수 있습니다.

다른 입력값으로 잡을 재시도하려면:

1. 잡 세부 정보 페이지로 이동합니다.
2. Retry job with modified values ([chevron-down])를 선택합니다.
3. 양식에서 입력값이 이전 실행의 값으로 미리 채워져 있습니다. 필요에 따라 입력값을 수정합니다.
4. Run job again을 선택합니다.

동일한 입력값으로 재시도하려면 대신 Retry ([retry])를 선택합니다.

잡 입력값 예시#

입력값이 있는 기본 배포 잡#

deploy:
  when: manual
  inputs:
    target_env:
      default: staging
      description: Target deployment environment
      options: [staging, production]
    version:
      default: latest
      description: Application version to deploy
  script:
    - 'echo "Deploying version ${{ job.inputs.version }} to ${{ job.inputs.target_env }}"'
    - ./deploy.sh --env ${{ job.inputs.target_env }} --version ${{ job.inputs.version }}

유효성 검사가 있는 테스트 잡#

integration_tests:
  inputs:
    test_suite:
      default: smoke
      description: Which test suite to run
      options: [smoke, regression, full]
    parallel_jobs:
      type: number
      default: 5
      description: Number of parallel test runners
    enable_debug:
      type: boolean
      default: false
      description: Enable debug logging
    tags:
      type: array
      default: ["critical"]
      description: Test tags to run
  script:
    - 'if [ "${{ job.inputs.enable_debug }}" == "true" ]; then export DEBUG=1; fi'
    - ./run_tests.sh
        --suite ${{ job.inputs.test_suite }}
        --parallel ${{ job.inputs.parallel_jobs }}
        --tags '${{ job.inputs.tags }}'

안전 점검이 있는 데이터베이스 마이그레이션#

migrate_database:
  when: manual
  inputs:
    target_db:
      default: development
      description: Database environment
      options: [development, staging, production]
    migration_name:
      default: ""
      description: Specific migration to run (leave empty for all)
      regex: ^[a-zA-Z0-9_]*$
    dry_run:
      type: boolean
      default: true
      description: Run in dry-run mode without applying changes
  script:
    - 'echo "Running migrations on ${{ job.inputs.target_db }}"'
    - |
      if [ "${{ job.inputs.dry_run }}" == "true" ]; then
        echo "DRY RUN MODE - no changes will be applied"
        MIGRATION_FLAGS="--dry-run"
      fi
    - |
      if [ -n "${{ job.inputs.migration_name }}" ]; then
        ./migrate.sh $MIGRATION_FLAGS --migration ${{ job.inputs.migration_name }}
      else
        ./migrate.sh $MIGRATION_FLAGS --all
      fi

API로 잡 입력값 사용#

API를 사용하여 잡을 실행하거나 재시도할 때 잡 입력값을 지정할 수 있습니다.

입력값으로 수동 잡 실행#

job_inputs 매개변수와 함께 POST /projects/:id/jobs/:job_id/play 엔드포인트를 사용합니다:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "job_inputs": {
      "environment": "staging",
      "version": "v2.1.0"
    }
  }' \
  "https://gitlab.example.com/api/v4/projects/1/jobs/456/play"

입력값으로 잡 재시도#

job_inputs 매개변수와 함께 POST /projects/:id/jobs/:job_id/retry 엔드포인트를 사용합니다:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "job_inputs": {
      "environment": "production",
      "replicas": 10
    }
  }' \
  "https://gitlab.example.com/api/v4/projects/1/jobs/123/retry"

GraphQL 사용#

inputs 인자와 함께 jobPlay 뮤테이션 또는 jobRetry 뮤테이션을 사용할 수 있습니다:

mutation {
  jobPlay(input: {
    id: "gid://gitlab/Ci::Build/123",
    inputs: [
      { name: "environment", value: "production" },
      { name: "replicas", value: 10 }
    ]
  }) {
    job {
      id
      status
    }
    errors
  }
}

문제 해결#

input must have a default value 오류로 잡 실패#

잡 입력값에는 입력값을 수동으로 지정할 수 없는 파이프라인에서도 잡이 실행될 수 있도록 항상 기본값이 있어야 합니다.

이 오류를 수정하려면 모든 입력에 default를 추가하세요:

my_job:
  inputs:
    target_env:
      default: staging  # Default specified
  script:
    - echo ${{ job.inputs.target_env }}

unexpected value로 입력 유효성 검사 실패#

입력 유효성 검사가 실패하면 다음을 확인하세요:

• options를 사용하는 경우, 값이 허용된 옵션 중 하나와 정확히 일치하는지 확인합니다(대소문자 구분).
• regex를 사용하는 경우, 정규식이 입력값과 일치하는지 테스트합니다.
• type: number를 사용하는 경우, 값이 문자열이 아닌 숫자인지 확인합니다.
• type: array를 사용하는 경우, API를 통해 전달할 때 값이 JSON 배열 형식인지 확인합니다.