잡 입력

잡 입력 (Job inputs)

  • GitLab 18.10에서 도입됐어요.
  • GitLab Runner 18.9 이상이 필요해요.

잡 입력(job inputs)을 사용하면 개별 CI/CD 잡에 대해 타입이 정해지고 검증되는 파라미터를 정의할 수 있어요. 이 값은 잡을 수동으로 실행하거나 재시도할 때 재정의할 수 있어요. CI/CD 변수와 달리 잡 입력은 다음을 제공해요:

  • 타입 안전성(type safety): 입력은 string, number, boolean, array가 될 수 있고 자동으로 검증돼요.
  • 명시적 계약(explicit contract): 잡은 정의한 입력만 받아요. 예상치 못한 입력은 거부돼요.
  • 재정의 기능: 입력 값은 잡을 실행할 때 설정하고, 재시도할 때 변경할 수 있어요.

잡 입력은 잡 동작을 제어하면서도 재실행 시 조정이 필요할 수 있는 파라미터에 사용하세요. 예: 배포 대상, 테스트 구성, 기능 플래그 등.

잡 입력은 정의된 잡에만 적용되며, 포함된 파일이나 다른 잡에서는 접근할 수 없어요. 여러 잡이나 파일에 걸쳐 구성을 공유해야 한다면 대신 CI/CD 구성 입력을 사용하세요.

출처: 문서

본문

잡 입력 비교

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

잡 입력과 CI/CD 파이프라인 구성 입력은 목적이 달라요:

Feature Job inputs CI/CD configuration inputs
Purpose Configure individual job behavior Configure reusable templates and components
Syntax inputs: in job definition spec:inputs: in configuration header
Interpolation ${{ job.inputs.INPUT_NAME }} $[[ inputs.INPUT_NAME ]]
Evaluation Values set when job is created, can be overridden when running/retrying Values set at pipeline creation, fixed for entire pipeline
Default values Required Optional
Scope Single job only Entire configuration file or passed to included files

환경 변수와 비교

잡 입력은 잡이 생성될 때 잡 구성으로 보간(interpolate)돼요. 이는 환경 변수가 아니며 $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 mutation 또는 jobRetry mutation을 사용할 수 있어요:

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 배열 형식인지 확인하세요.

더 알아보기

다음으로는 CI/CD 파이프라인 구성 입력 문서와 Moa 표현식 언어를 함께 보면, 재사용 템플릿과 동적 파이프라인 구성까지 다루는 완성도 높은 입력 설계를 익힐 수 있어요.