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

함수는 재사용 가능하고 구성 가능한 잡의 조각입니다. 각 함수는 다른 함수가 사용할 수 있는 구조화된 입력과 출력을 정의합니다. 로컬 파일, GitLab.com 저장소 또는 다른 Git 소스에서 함수를 구성할 수 있습니다.

이 튜토리얼에서는 GitLab CLI(glab)를 사용하여 다음을 수행합니다:

1. "hello world"를 출력하는 함수를 생성합니다.
2. 함수를 사용하도록 파이프라인을 구성합니다.
3. 잡에 여러 함수를 추가합니다.
4. 원격 함수를 사용하여 모든 출력을 에코합니다.

시작하기 전에#

• GitLab CLI(glab)를 설치하고 로그인해야 합니다.

함수 생성#

먼저 다음을 사용하는 함수를 생성합니다:

• 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:
         type: string
         default: world
   

   • spec에는 who라는 하나의 입력이 있습니다.
   • 기본값이 있기 때문에 who 입력은 선택 사항입니다.

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

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

세 개의 대시(---)는 파일을 두 개의 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:
     run:
       - name: hello_world
         step: .
   

   • run 키워드에는 함수 호출 목록이 있습니다.
     • 각 호출에는 이후 함수에서 출력을 참조할 수 있도록 name이 지정됩니다.
     • 각 호출은 실행할 step을 지정합니다. 로컬 참조(.)는 저장소의 루트를 가리킵니다.

   이 코드가 저장소에서 어떻게 보여야 하는지 예시는 Steps 튜토리얼, 1부를 참조하세요.

3. 두 파일을 모두 커밋하고 프로젝트 저장소를 푸시합니다. 이렇게 하면 잡을 실행하는 파이프라인이 트리거됩니다:

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

4. 파이프라인이 완료될 때까지 "View Logs" 아래의 잡을 따라갑니다. 다음은 성공적인 잡의 예입니다:

   Step Runner version: a7c7c8fd
   See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
   ...
   hello world
   Cleaning up project directory and file based variables
   Job succeeded
   

첫 번째 함수를 생성하고 사용했습니다!

잡에 여러 함수 추가#

잡에 두 개 이상의 함수를 가질 수 있습니다.

1. .gitlab-ci.yml 파일에서 잡에 hello_steps라는 또 다른 함수를 추가합니다:

   hello-world:
     run:
       - name: hello_world
         step: .
       - name: hello_steps
         step: .
         inputs:
           who: gitlab functions
   

   이 hello_steps 함수는 gitlab functions의 기본값이 아닌 who 입력을 제공합니다.

   이 코드가 저장소에서 어떻게 보여야 하는지 예시는 Steps 튜토리얼, 2a부를 참조하세요.

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

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

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

   Step Runner version: a7c7c8fd
   See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
   ...
   hello world
   hello gitlab functions
   Cleaning up project directory and file based variables
   Job succeeded
   

함수 리팩토링#

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

1. 처음 생성한 함수를 hello라는 디렉토리로 이동합니다:

   mkdir hello
   mv step.yml hello/
   

2. 저장소의 루트에 새 함수를 생성합니다.

   touch step.yml
   

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

   spec:
   ---
   run:
     - name: hello_world
       step: ./hello
     - name: hello_steps
       step: ./hello
       inputs:
         who: gitlab functions
   

   이 새 함수에는 입력이 없으므로 spec이 비어 있습니다. .gitlab-ci.yml의 함수와 동일한 구문을 가진 steps 유형입니다. 그러나 로컬 참조는 이제 hello 디렉토리의 함수를 가리킵니다.

4. 새 함수를 사용하려면 .gitlab-ci.yml을 수정합니다:

   hello-world:
     run:
       - name: hello_everybody
         step: .
   

   이제 잡은 입력 없이 새 함수만 호출합니다. 잡의 세부 사항을 별도 파일로 리팩토링했습니다.

   이 코드가 저장소에서 어떻게 보여야 하는지 예시는 Steps 튜토리얼, 2b부를 참조하세요.

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

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

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

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

   $ /step-runner ci
   hello world
   hello gitlab functions
   Cleaning up project directory and file based variables
   Job succeeded
   

함수에 출력 추가#

hello 함수에 출력을 추가합니다.

1. hello/step.yml에서 spec에 outputs 구조를 추가합니다:

   spec:
     inputs:
       who:
         type: string
         default: world
     outputs:
       greeting:
         type: string
   ---
   exec:
     command:
       - bash
       - -c
       - echo '{"name":"greeting","value":"hello ${{inputs.who}}"}' | tee ${{output_file}}
   

   • 이 spec에서 기본값 없이 단일 출력 greeting을 정의했습니다. 기본값이 없기 때문에 greeting 출력은 필수입니다.
   • 출력은 런타임에 제공된 ${{output_file}} 파일에 JSON Line 형식으로 작성됩니다. 출력 파일에 작성된 각 줄은 name과 value 두 개의 키를 가진 JSON 객체여야 합니다.
   • 이 함수는 echo '{"name":"greeting","value":"hello ${{inputs.who}}"}'를 실행하고 출력을 잡 로그와 출력 파일(tee ${{output_file}})로 보냅니다.

2. step.yml에서 단계에 출력을 추가합니다:

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

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

   이 출력은 표현식 구문을 보여줍니다: ${{steps.hello_world.outputs.greeting}}. all_greetings는 두 하위 단계 hello_world와 hello_steps의 출력을 읽습니다. 두 하위 단계 출력이 단일 문자열 출력으로 연결됩니다.

원격 함수 사용#

코드를 커밋하고 실행하기 전에, 주 step.yml의 최종 all_greetings 출력을 보기 위해 잡에 또 다른 함수를 추가합니다.

이 함수 호출은 echo-step이라는 원격 함수를 참조합니다. 에코 함수는 단일 입력 echo를 받아 로그에 출력하고 echo로 출력합니다.

1. .gitlab-ci.yml을 편집합니다:

   hello-world:
     run:
       - name: hello_everybody
         step: .
       - name: all_my_greetings
         step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
         inputs:
           echo: "all my greetings say ${{steps.hello_everybody.outputs.all_greetings}}"
   

   이 코드가 저장소에서 어떻게 보여야 하는지 예시는 Steps 튜토리얼, 2c부를 참조하세요.

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

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

3. 파이프라인이 완료될 때까지 "View Logs" 아래의 잡을 따라갑니다. 다음은 성공적인 출력의 예입니다:

   Step Runner version: a7c7c8fd
   See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
   ...
   {"name":"greeting","value":"hello world"}
   {"name":"greeting","value":"hello gitlab functions"}
   all my greetings say hello world and hello gitlab functions
   Cleaning up project directory and file based variables
   Job succeeded
   

완료했습니다! 파이프라인에서 함수를 생성하고 구현했습니다. 함수 구문에 대한 자세한 내용은 CI/CD 함수를 참조하세요.