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

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

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

1. "hello world"를 출력하는 함수를 만듭니다.
2. 함수를 사용하는 파이프라인을 구성합니다.
3. Job에 여러 함수를 추가합니다.
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에 다음 Job을 추가합니다:

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

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

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

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

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

4. "View Logs" 아래에서 Job을 따라가며 파이프라인이 완료될 때까지 기다립니다. 성공적인 Job의 예시입니다:

   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
   

첫 번째 함수를 만들고 사용했습니다!

Job에 여러 함수 추가#

Job에 여러 개의 함수를 가질 수 있습니다.

1. .gitlab-ci.yml 파일에서 Job에 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: .
   

   이제 Job은 입력 없이 새 함수만 호출합니다. Job의 세부 정보를 별도 파일로 리팩토링했습니다.

   이 코드가 리포지터리에서 어떻게 보여야 하는지에 대한 예시는 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}}"}'를 실행하고 출력을 Job 로그와 출력 파일(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 출력을 보기 위해 Job에 또 다른 함수를 추가합니다.

이 함수 호출은 echo-step이라는 원격 함수를 참조합니다. echo 함수는 단일 입력 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" 아래에서 Job을 따라가며 파이프라인이 완료될 때까지 기다립니다. 성공적인 출력의 예시입니다:

   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 Functions를 참조하세요.