CI/CD 단계

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
Status: Experimental

단계는 작업의 재사용 가능하고 구성 가능한 구성 요소입니다.

각 단계는 다른 단계에서 사용할 수 있는 구조화된 입력 및 출력을 정의합니다.

단계는 로컬 파일, GitLab.com 저장소 또는 기타 Git 소스에서 올 수 있습니다.

단계는 작업 실행을 위한 셸 스크립트의 대안입니다.

더 많은 구조를 제공하며, 조합할 수 있고, 테스트 및 재사용할 수 있습니다.

exec:command는 셸을 실행하는 것이 아니라 Exec 시스템 호출을 사용하여 실행됩니다.

시작하려면 단계 설정 튜토리얼을 참조하세요.

단계를 게시하는 CI 카탈로그에 대한 지원이 issue 425891에서 제안되었습니다.

단계 정의

단계는 step.yml 파일에 정의됩니다.

각 파일에는 두 개의 문서가 있으며, 스펙과 정의입니다.

스펙은 입력, 출력, 유형, 설명 및 기본값을 제공합니다.

# 예제 스펙
spec:
  inputs:
    name:
      type: string
      default: joe steppy
---
# (정의가 여기에 들어갑니다)

정의는 단계의 구현을 제공합니다.

단계 정의에는 두 가지 종류가 있습니다:

명령을 실행하는 exec 유형입니다.

# (스펙이 여기에 들어갑니다)
---
# 예제 exec 정의
exec:
command: [ docker, run, -it, ubuntu, uname, -a ]

다른 단계의 시퀀스를 실행하는 steps 유형입니다.

# (스펙이 여기에 들어갑니다)
---
# 예제 steps 정의
steps:
  - name: greet_user
    step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
    inputs:
      echo: hello ${{ inputs.name }}
  - name: print_system_information
    step: ./my-local-steps/uname

단계 구현을 리팩토링할 수 있도록, 단계는 exec에서 steps 유형으로 변경할 수 있으며, exec에서 steps 유형으로 변경해도 워크플로우(또는 호출 단계)에 영향을 주지 않습니다.

입력

입력의 유형은 다음과 같습니다:

string
number
boolean
array
struct

기본 입력 유형은 string입니다.

입력이 기본값을 정의하지 않으면 필수입니다.

기본값은 단계 정의에서만 허용되는 표현식(${{ }})을 사용할 수 없습니다.

출력

출력의 유형은 다음과 같습니다:

string
number
boolean
array
struct
raw_string
step_result

출력은 key=value 형식으로 ${{ output_file }}에 기록되며, 여기서 key는 출력의 이름입니다.

value는 유형이 raw_string이 아닐 경우 JSON 형식으로 작성되어야 합니다.

단계에서 작성된 값의 유형은 선언된 유형과 일치해야 합니다. 기본 출력 유형은 raw_string입니다.

특수 출력 유형인 step_result는 다른 단계에 단계 실행을 위임할 때 사용됩니다.
예를 들어, script 및 action-runner 단계입니다.

steps 유형 정의의 출력은 서브 단계 출력에서 집계하기 위해 표현식을 사용합니다.
스펙에서 표현식이 허용되지 않기 때문에 outputs 키워드가 정의에 나타납니다.
캡슐화를 보존하고 리팩토링할 수 있도록 호출자는 서브 단계의 출력에 직접 접근할 수 없습니다.

# 여러 단계의 예제 출력
spec:
  outputs:
    full_name:
      type: string
---
steps:
  - name: first_name
    step: ./fn
  - name: last_name
    step: ./ln
outputs:
  full_name: "hello ${{ steps.first_name.outputs.name }} ${{ steps.last_name.outputs.name }}"

사용 단계

키워드 step은 원격 또는 로컬 단계를 가리킵니다.

원격 단계 참조는 Git 저장소의 URL, 문자 @, 그리고 태그 또는 브랜치(버전)입니다.

단계 실행기는 저장소의 루트에 있는 step.yml 파일을 찾습니다.

로컬 단계는 .으로 시작하며, 단계 실행기가 step.yml을 찾는 디렉토리를 가리킵니다.

로컬 참조는 운영 체제와 관계없이 항상 경로 구분자 /를 사용합니다.

파일을 로드할 때는 운영 체제에 적합한 구분자가 사용됩니다.

# 단계 사용 예제 작업
my-job:
  run:
    - name: greet_user
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
      inputs:
        echo: hello $[[ GITLAB_USER_LOGIN ]]
    - name: print_system_information
      step: ./my-local-steps/uname

작업에서 단계를 사용하려면, 변수를 통해 단계를 제공하고 script 키워드로 단계 실행기를 호출해야 합니다.

GitLab CI 파이프라인 구성에서 run 키워드로 작업에서 단계를 사용하는 지원은 epic 11525에 제안되었습니다.

# run 키워드가 구현될 때까지의 우회 예제
my-job:
  image: registry.gitlab.com/gitlab-org/step-runner:v0
  variables:
    STEPS: |
      - name: greet_user
        step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
        inputs:
          echo: hello $GITLAB_USER_LOGIN
      - name: print_system_information
        step: ./my-local-steps/uname
  script:
    # STEPS 환경 변수를 준비하여 step-runner의 ci 명령을 실행합니다
    - /step-runner ci

환경 변수 설정

단계에 대해 환경 변수를 선언할 필요는 없습니다.

${{ export_file }}에 key=value 형식으로 작성된 모든 내보내기는 전역 실행 환경에 추가됩니다.

내보낸 값은 일반 문자열입니다(제대로 처리된 JSON 아님).

env 키워드를 단계를 위해 사용하여 실행 중에 환경 변수를 임시로 설정할 수 있습니다:

# env를 사용한 예제 작업
my-job:
  run:
    - name: greet_user
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
      env:
        USER: $[[ GITLAB_USER_LOGIN ]]
      inputs:
        echo: hello ${{ env.USER }}

단계 정의 또한 환경 변수를 임시로 설정할 수 있습니다.

# (spec는 여기에)
---
# env를 사용한 단계 정의 예제
env:
  USER: ${{ inputs.user }}
steps:
  - name: greet_user
    step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
    inputs:
      echo: hello ${{ env.USER }}

환경 변수의 우선 순위는 다음과 같습니다:

단계 정의
단계 참조(단계를 호출하는 것)
전역 환경

단계 정의에서 설정된 env 변수가 단계를 호출할 때 설정된 변수를 덮어쓰고, 이와 같습니다.

로컬에서 단계 실행

로컬에서 단계를 실행하려면, step-runner를 다운로드하고 ci 명령을 실행하세요.

이는 프로덕션에서 단계를 실행하는 데 사용되는 동일한 바이너리입니다.

STEPS=$(yq '."my-job"'.run .gitlab-ci.yml) step-runner ci

delve를 사용하여 디버깅할 수 있습니다.

pkg/runner.go의 Run에서 중단점을 설정하세요.

STEPS=$(yq '."my-job"'.run .gitlab-ci.yml) dlv debug . ci

스크립트

단계는 일반적으로 셸 스크립트 대신 사용되지만, 때때로 셸 스크립트가 여전히 필요합니다.

script 키워드는 자동으로 올바른 셸을 선택하고 스크립트를 실행합니다.

# 스크립트를 사용하는 예제 작업
my-job:
  run:
    - name: greet_user
      script: echo hello $[[ GITLAB_USER_LOGIN ]]

오직 bash 셸만 지원됩니다. 조건 표현식에 대한 지원은 epic 12168에서 제안되었습니다.

액션

action 키워드를 사용하여 GitHub 액션을 실행할 수 있습니다.

입력과 출력은 단계와 동일한 방식으로 작동합니다.

단계와 액션은 상호 교환하여 사용할 수 있습니다.

# 액션을 사용하는 예제 작업
my-job:
  run:
    - name: greet_user
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1
      inputs:
        echo: hello $[[ GITLAB_USER_LOGIN ]]
    - name: greet_user_again
      action: mikefarah/yq@master
      inputs:
        cmd: echo ["${{ steps.greet_user.outputs.echo }} again!"] | yq .[0]

알려진 문제

GitLab에서 실행되는 액션은 아티팩트를 직접 업로드하는 것을 지원하지 않습니다.

아티팩트는 파일 시스템과 캐시에 써야 하며, 기존의 artifacts 키워드로 선택해야 합니다.

액션을 실행하려면 dind 서비스가 필요합니다.

자세한 내용은 Docker를 사용하여 Docker 이미지 빌드하기를 참조하십시오.

GitLab의 액션은 실험적이며 버그가 포함될 수 있습니다.

버그를 보고하려면 action-runner repo에서 이슈를 생성하십시오.

표현식

표현식은 중괄호 두 개(${{ }})로 묶인 미니 언어입니다.

이들은 inputs, env(단계 간에 공유되는 환경) 및 이전 단계의 출력(steps.<step_name>.outputs)을 참조할 수 있습니다.

표현식은 빌드 디렉토리인 work_dir를 참조할 수도 있습니다.

그리고 단계 정의와 관련 파일이 캐시된 step_dir입니다.

또한 출력과 수출이 작성되는 output_file 및 export_file을 참조할 수 있습니다.

표현식은 단계 생성 동안 평가되는 이중 대괄호($[[ ]])를 사용하는 템플릿 보간과 다릅니다.

표현식은 작업 환경에서 단계 실행 직전에 평가됩니다.

CI/CD 단계

단계 정의

입력

출력

사용 단계

환경 변수 설정

로컬에서 단계 실행

스크립트

액션

알려진 문제

표현식

도움말

기능 사용 가능성과 제품 평가판

도움받기