튜토리얼: CI/CD 단계 설정하기

이 튜토리얼에서는 파이프라인에서 단계(step)를 생성하고 사용하는 방법을 보여줍니다.

단계는 작업의 재사용 가능하고 조합할 수 있는 구성 요소입니다. 각 단계는 다른 단계에서 사용할 수 있는 구조화된 입력 및 출력을 정의합니다. 단계는 로컬 파일, GitLab.com 리포지토리 또는 기타 Git 소스에서 구성할 수 있습니다.

이 튜토리얼에서는 GitLab CLI(glab)를 사용하여:

  1. “hello world”를 출력하는 단계를 생성합니다.
  2. 단계를 사용하도록 파이프라인을 구성합니다.
  3. 작업에 여러 단계를 추가합니다.
  4. 모든 출력을 에코하는 원격 단계를 사용합니다.

시작하기 전에

  • GitLab CLI (glab)를 설치하고 로그인해야 합니다.
  • GitLab.com 및 GitLab 17.3 이상에서 자체 관리의 경우, .gitlab-ci.yml 파일에 image: registry.gitlab.com/gitlab-org/step-runner:v0 러너 이미지를 포함해야 합니다.

단계 생성하기

먼저 다음과 같이 단계(create step)를 생성합니다:

  • exec 유형
  • 시스템의 실행 API에 의해 시작되는 command

  1. 자신의 네임스페이스에 zero-to-steps라는 이름의 GitLab 프로젝트를 생성합니다:

    glab project create zero-to-steps

  2. 프로젝트 리포지토리의 루트로 이동합니다:

    cd zero-to-steps

  3. step.yml 파일을 생성합니다.

    touch step.yml

  4. 텍스트 편집기를 사용하여 step.yml에 사양을 추가합니다:

    spec:
  inputs:
    who:
      default: world
    • spec에는 who라는 하나의 입력이 있습니다.
    • 입력 who는 기본값이 있으므로 선택적입니다.

  5. step.yml에 구현을 추가하려면 spec 다음에 exec 키로 두 번째 YAML 문서를 추가합니다:

    spec:
  inputs:
    who:
      default: world
---
exec:
  command:
    - bash
    - -c
    - "echo hello ${{ inputs.who }}"

세 개의 em 대시(---)는 파일을 두 개의 YAML 문서로 구분합니다:

  • 첫 번째 문서는 함수 시그니처와 같은 사양입니다.
  • 두 번째 문서는 함수 본체와 같은 구현입니다.

bash 및 -c 인수는 Bash 셸을 시작하고 명령줄 인수에서 스크립트 입력을 가져옵니다. 셸 스크립트 외에도 command를 사용하여 docker나 terraform과 같은 프로그램을 실행할 수 있습니다.

"echo hello ${{ input.name }}" 인수는 ${{와 }} 내부에 표현식을 포함합니다. 표현식은 가능한 마지막 순간에 평가되며 현재 실행 컨텍스트에 접근할 수 있습니다. 이 표현식은 inputs에 접근하고 who의 값을 읽습니다:

  • who가 호출자에 의해 제공될 경우, 해당 값이 표현식에 대체됩니다.
  • who가 생략될 경우, 기본값인 world가 표현식에 대체됩니다.

단계를 사용하도록 파이프라인 구성하기

  1. 리포지토리의 루트에서 .gitlab-ci.yml 파일을 생성합니다:

    touch .gitlab-ci.yml

  2. .gitlab-ci.yml에 다음 작업을 추가합니다:

     hello-world:
   variables:
     STEPS:
       expand: false
       value: |
         - name: hello_world
           step: .
   image: registry.gitlab.com/gitlab-org/step-runner:v0
   script:
     - /step-runner ci
    • 단계는 STEPS라는 환경 변수에 제공됩니다. STEPS는 단계 호출의 목록입니다.
      • 각 호출에는 나중에 출력을 참조할 수 있도록 name이 지정됩니다.
      • 각 호출은 실행할 step을 지정합니다. 로컬 참조(.)는 리포지토리의 루트를 가리킵니다.
    • 작업 스크립트는 step-runner ci를 호출하며, 이는 step-runner:v0 이미지에 있습니다.

    이 코드가 리포지토리에서 어떻게 보여야 하는지에 대한 예시는 이 예시를 참조하세요.

  3. 두 파일을 커밋하고 프로젝트 리포지토리를 푸시합니다. 그러면 작업을 실행하는 파이프라인이 트리거됩니다:

    git add .
git commit -m 'Part 1 complete'
git push --set-upstream origin master
glab ci status

  4. 파이프라인이 완료될 때까지 “로그 보기” 아래에서 작업을 추적합니다. 성공적인 작업의 예시는 다음과 같습니다:

    $ /step-runner ci
hello world
trace written to step-results.json
Cleaning up project directory and file based variables
Job succeeded

참고:

환경 변수 사용은 run 키워드가 구현될 때까지의 임시 대안입니다.

run 키워드 에픽을 참조하세요.

이제 첫 번째 단계를 생성하고 사용했습니다!

작업에 여러 단계를 추가하기

작업에 여러 단계를 가질 수 있습니다.

  1. .gitlab-ci.yml 파일에서 hello_steps라는 또 다른 단계를 작업에 추가합니다:

    hello-world:
  variables:
    STEPS:
      expand: false
      value: |
        - name: hello_world
          step: .
        - name: hello_steps
          step: .
          inputs:
            who: gitlab steps
  image: registry.gitlab.com/gitlab-org/step-runner:v0
  script:
    - /step-runner ci

    이 hello_steps 단계는 비기본 입력 who를 gitlab steps로 제공합니다.

    이 코드가 귀하의 리포지토리에서 어떻게 보이는지에 대한 예시는 이 예제를 참조하세요.

  2. 변경 사항을 커밋하고 푸시합니다:

    git commit -a -m 'Added another step'
git push
glab ci status

  3. 터미널에서 View Logs를 선택하고 파이프라인이 완료될 때까지 따라갑니다. 성공적인 출력의 예는 다음과 같습니다:

    $ /step-runner ci
hello world
hello gitlab steps
trace written to step-results.json
Cleaning up project directory and file based variables
Job succeeded

단계를 리팩토링하기

단계를 리팩토링하려면, .gitlab-ci.yml에서 전용 파일로 이동합니다:

단계를 CI Config에서 전용 파일로 이동하여 리팩토링합니다:

  1. 생성한 첫 번째 단계를 hello라는 디렉터리로 이동합니다:

    mkdir hello
mv step.yml hello/

  2. 리포지토리의 루트에 새 단계를 만듭니다.

    touch step.yml

  3. 다음 구성을 새 step.yml에 추가합니다:

    spec: {}
---
steps:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab steps

    이 새로운 단계는 입력이 없으므로 spec이 비어 있습니다 ({}).

    이는 .gitlab-ci.yml의 단계와 동일한 구문을 가진 steps 유형입니다.

    그러나 이제 로컬 참조는 hello 디렉터리의 단계로 향합니다.

  4. 새 단계를 사용하기 위해 .gitlab-ci.yml을 수정합니다:

    hello-world:
  variables:
     STEPS:
       expand: false
       value: |
         - name: hello_everybody
           step: .
  image: registry.gitlab.com/gitlab-org/step-runner:v0
  script:
    - /step-runner ci

    이제 작업은 입력 없이 새 단계만 호출합니다.

    작업의 세부 사항을 별도의 파일로 리팩토링했습니다.

    이 코드가 귀하의 리포지토리에서 어떻게 보이는지에 대한 예시는 이 예제를 참조하세요.

  5. 변경 사항을 커밋하고 푸시합니다:

    git add .
git commit -m 'Refactored step config'
git push
glab ci status

  6. 터미널에서 View Logs를 선택합니다.

  7. 리팩토링된 단계가 처음 생성한 단계와 동일한 기능을 수행하는지 확인하기 위해 로그 출력을 봅니다. 로그 출력은 이전에 생성한 단계의 출력과 일치해야 합니다. 예시는 다음과 같습니다:

    $ /step-runner ci
hello world
hello gitlab steps
trace written to step-results.json
Cleaning up project directory and file based variables
Job succeeded

단계에 출력을 추가하세요

당신의 hello 단계에 출력을 추가하세요.

  1. hello/step.yml에서 spec에 outputs 구조를 추가하세요:

    spec:
  inputs:
    who:
      default: world
  outputs:
    greeting: {}
---
exec:
  command:
    - bash
    - -c
    - "echo greeting=hello ${{ inputs.who }} | tee ${{ output_file }}"
    • 이 spec에서는 기본값 없이 단일 출력 greeting을 정의했습니다. 기본값이 없기 때문에 출력 greeting은 필수입니다.
    • 출력은 실행 시 제공된 파일 ${{ output_file }}에 key=value 형식으로 작성됩니다.
    • 이 단계는 echo greeting=hello ${{ inputs.name }}를 실행하고 출력을 로그와 출력 파일(tee ${{ output_file }})로 보냅니다.

  2. step.yml에서 단계에 출력을 추가하세요:

    spec:
  outputs:
    all_greetings: {}
---
steps:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab steps
outputs:
  all_greetings: "${{ steps.hello_world.outputs.greeting }} and ${{ steps.hello_steps.outputs.greeting }}"

이제 all_greetings라는 출력을 이 단계에 추가했습니다.

이 출력은 새로운 표현식 구문 ${{ steps.hello_world.outputs.greeting }}의 사용을 보여줍니다.

이 표현식은 두 개의 하위 단계인 hello_world와 hello_steps의 outputs를 읽습니다.

두 하위 단계의 출력이 단일 문자열 출력으로 연결됩니다.

원격 단계 사용하기

코드를 커밋하고 실행하기 전에, 작업에 또 다른 단계를 추가하여 주요 step.yml의 최종 all_greetings 출력을 확인하세요.

이 단계 호출은 echo-step라는 원격 단계를 참조합니다.

echo 단계는 단일 입력 echo를 받아서 로그에 출력하고 echo로 출력합니다.

  1. .gitlab-ci.yml을 수정하세요:

    hello-world:
  variables:
    STEPS:
      expand: false
      value: |
        - name: hello_everybody
          step: .
        - name: all_my_greetings
          step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@master
          inputs:
            echo: "all my greetings say ${{ steps.hello_everybody.outputs.all_greetings }}"
  image: registry.gitlab.com/gitlab-org/step-runner:v0
  script:
    - /step-runner ci

    이 코드가 리포지토리에 어떻게 보여야 하는지에 대한 예시는 이 예시를 참조하세요.

  2. 변경 사항을 커밋하고 푸시하세요:

    git commit -a -m 'Added outputs'
git push
glab ci status

  3. 파이프라인이 완료될 때까지 “로그 보기”에서 작업을 따르세요. 다음은 성공적인 출력 예시입니다:

    $ /step-runner ci
greeting=hello world
greeting=hello gitlab steps
echo=all my greetings say hello world and hello gitlab steps
trace written to step-results.json
Cleaning up project directory and file based variables
Job succeeded

그게 다입니다! 이제 당신은 파이프라인에서 단계를 생성하고 구현했습니다.

단계의 구문에 대한 자세한 정보는 CI/CD Steps를 참조하세요.