GitLab Functions는 GitLab CI/CD 잡에서 script를 대체하는 재사용 가능한 CI/CD 잡 로직 단위입니다.

함수를 사용하는 이유#

파이프라인이 성장하면 script 블록은 유지 관리하기 어려워집니다. 잡 간에 로직이 중복되고, 잡이 런타임에 외부 소스에서 스크립트를 가져오며, 작은 변경 사항이 여러 곳에서 업데이트가 필요합니다. GitLab Functions는 이러한 문제를 해결하기 위해 설계되었습니다.

함수의 장점:

• 함수는 자체적으로 포함되어 있고 버전 관리됩니다. 함수는 로직, 지원 스크립트 또는 바이너리, 입력과 출력을 설명하는 사양을 패키징하는 OCI 이미지입니다. 스텝이 실행될 때 GitLab이 자동으로 함수를 가져옵니다. 잡 시작 시 스크립트를 가져오거나 외부 의존성을 수동으로 관리할 필요가 없습니다. 특정 버전 태그에서 함수를 참조하면 매번 정확히 그 버전을 얻습니다.

• 함수는 잡과 프로젝트 간에 재사용 가능합니다. OCI 레지스트리에 함수를 게시하면 모든 잡이 각 저장소에 스크립트 파일을 복사하고 유지 관리하지 않고 단일 func 참조로 함수를 사용할 수 있습니다.

• 함수는 데이터 흐름을 명시적으로 만듭니다. script 블록에서 값은 임의의 순서로 설정, 덮어쓰기, 읽을 수 있는 셸 변수를 통해 명령 간에 전달됩니다. run 목록에서 각 스텝은 입력과 출력을 선언하며, 스텝은 이미 실행된 스텝의 출력에만 접근할 수 있습니다.

• 함수는 독립적으로 테스트 가능합니다. 함수가 입력과 출력을 정의하기 때문에 전체 파이프라인을 실행하지 않고도 격리하여 실행하고 테스트할 수 있습니다.

• 함수 실행은 플랫폼 간에 신뢰할 수 있습니다. 전용 에이전트가 네트워크를 통해 전송된 스크립트를 해석하는 것이 아니라 빌드 호스트에서 함수 실행을 관리합니다. 이는 함수에 적절한 프로세스 제어, 크로스 플랫폼 일관성, 재개 가능한 잡의 기반을 제공합니다. 이러한 기능은 셸 스크립트만으로는 달성하기 어렵거나 불가능합니다.

기존 셸 스크립트를 재사용하려면 script 스텝을 사용하여 점진적으로 마이그레이션하면서 run 목록에서 직접 실행합니다. 모든 것을 한 번에 변환하지 않고도 함수를 사용할 수 있습니다.

함수 이해#

전통적인 CI/CD 잡에서 script 키워드는 셸 명령 목록을 포함합니다. 잡은 모든 스텝을 소유하고 로직이 YAML에 직접 존재하며, 결과를 달성하는 방법을 정확히 설명합니다. 파이프라인이 성장하면 이 접근 방식은 재사용, 테스트, 프로젝트 간 공유가 어려워집니다.

GitLab Functions를 사용하면 run 키워드를 사용하여 스텝 목록을 선언합니다. 각 스텝은 구현을 포함하는 함수를 참조하며, 잡은 방법보다 무엇이 발생해야 하는지를 설명합니다. 로직은 YAML이 아닌 함수에 존재합니다.

다음은 JavaScript 프로젝트의 전통적인 .gitlab-ci.yml 예시입니다:

build_and_release:
  script:
    - npm run lint
    - npm test
    - npm run bundle
    - BUNDLE_PATH=$(find dist -name '*.js' | head -1)
    - npm run minify -- --input $BUNDLE_PATH
    - npm run deploy -- --artifact $MINIFIED_PATH --env production

GitLab Functions로 작성된 동일한 파이프라인:

build_and_release:
  run:
    - name: validate
      func: registry.gitlab.com/js/validate:1.0.0
    - name: release
      func: registry.gitlab.com/js/release:1.0.0
      inputs:
        environment: production

각 잡은 스텝을 통해 발생해야 할 것을 선언합니다. 함수 자체가 구현을 포함합니다.

GitLab Functions 용어집#

이 용어집은 GitLab Functions와 관련된 용어의 정의를 제공합니다.

함수(Function) : 재사용 가능한 자체 포함된 CI/CD 로직 패키지. 함수는 플랫폼별 컴파일된 코드, 입력과 출력을 정의하는 사양, 함수가 무엇을 하는지 설명하는 정의를 포함합니다. 함수는 명령을 실행하거나 다른 함수를 구성할 수 있습니다.

스텝(Step) : run 목록에서 함수의 단일 호출. 스텝은 이름, 함수 참조, 제공된 모든 입력, 해당 호출에 설정된 환경 변수를 포함합니다.

입력값(Inputs) : 스텝으로 호출할 때 함수에 전달하는 명명된 값. 입력값은 함수 사양에서 유형과 선택적 기본값으로 선언됩니다.

출력값(Outputs) : 함수가 실행된 후 반환하는 명명된 값. 출력값은 함수 사양에서 선언되고 실행 중에 출력 파일에 기록됩니다.

환경 변수 : 런타임에 함수에서 사용 가능한 변수. 환경 변수는 OS 프로세스 환경, 러너, 함수 정의, 스텝 호출, 또는 이전에 실행된 함수에서 내보낸 것에서 올 수 있습니다.

CI/CD Steps에서 이름 변경#

GitLab Functions는 이전에 CI/CD Steps라고 불렸습니다. 기능과 구문이 이름 변경되었습니다.

컴포넌트와 함수#

컴포넌트와 함수는 파이프라인의 다른 수준에서 작동하며 다른 문제를 해결합니다.

CI/CD 컴포넌트는 파이프라인 수준에서 재사용 가능합니다. GitLab은 잡이 실행되기 전에 컴포넌트를 포함하고 파이프라인에 잡, 스테이지, 구성을 기여합니다. 컴포넌트는 파이프라인에 어떤 잡이 있는지 설명합니다.

GitLab Functions는 잡 수준에서 재사용 가능합니다. 잡 내부에서 실행되며 script를 대체합니다.

컴포넌트와 함수는 다른 수준에서 작동하며 서로 잘 보완합니다. 컴포넌트는 잡을 정의하고 내부적으로 함수를 사용하여 구현할 수 있습니다. 컴포넌트를 포함하면 작동 방식을 알 필요 없이 완전히 구성된 잡을 얻습니다. 컴포넌트 작성자로서 함수를 사용하여 잡이 하는 것의 복잡성을 처리합니다.

표현식 구문#

컴포넌트와 함수는 다른 시점에 평가되기 때문에 다른 표현식 구문을 사용합니다:

• $[[ ]] 표현식은 파이프라인 생성 중에, 잡이 실행되기 전에 평가됩니다. CI/CD 입력값 및 컴포넌트 입력값에 이 구문을 사용합니다.
• ${{ }} 표현식은 잡 실행 중에, 각 스텝이 실행되기 직전에 평가됩니다. 함수 입력값, 환경 변수, 런타임 상태에 의존하는 값에 이 구문을 사용합니다.

두 구문 모두 CI/CD 컴포넌트 YAML 구성 파일에 나타날 수 있습니다:

spec:
  inputs:
    go_version:
      default: "1.22"
---

my-format-job:
  run:
    - name: install_go
      func: ./languages/go/install
      inputs:
        version: $[[ inputs.go_version ]]                      # resolved at pipeline creation
    - name: format
      func: ./languages/go/go-fmt
      inputs:
        go_binary: ${{ steps.install_go.outputs.go_binary }}   # resolved during job execution

함수 실행 모델#

함수는 입력값을 수락하고, 출력값을 반환하며, 환경 변수를 내보낼 수 있는 자체 포함된 패키지입니다. 함수는 호스트 머신이나 컨테이너이든 CI 잡의 환경에서 실행됩니다. 함수는 파일 시스템, OCI 레지스트리, 또는 Git 저장소에 로컬로 호스팅할 수 있습니다.

run 목록의 각 스텝은 순서대로 실행됩니다. 스텝은 공유 셸 상태 대신 입력값, 출력값, 내보낸 환경 변수를 통해 서로 통신합니다.

한 스텝의 출력값은 ${{ steps.<step-name>.outputs.<output-name> }} 표현식을 통해 후속 스텝에서 사용할 수 있습니다. 스텝이 내보낸 환경 변수는 모든 후속 스텝에서 사용할 수 있습니다. 출력값과 환경 변수는 모두 스텝이 완료된 후에만 사용할 수 있습니다.

러너가 run 목록이 있는 잡을 가져오면 스텝 러너를 호출하여 실행을 관리합니다. 목록의 각 스텝에 대해 스텝 러너는:

1. 함수 참조를 해결하고 파일 시스템, OCI 저장소, 또는 Git 저장소에서 함수 패키지를 가져옵니다.
2. 스텝의 입력값과 환경 변수의 모든 표현식을 평가합니다.
3. 함수를 실행하고 해결된 입력값과 환경을 전달합니다.
4. 함수가 출력 파일에 쓴 출력값을 읽고 후속 스텝에서 사용할 수 있도록 합니다.
5. 함수가 내보낸 환경 변수를 읽고 전역 환경에 추가합니다.
6. 다음 스텝으로 이동하거나 스텝이 실패하면 중지합니다.

함수 요구 사항#

함수를 사용하려면 사용하는 러너 실행기에 스텝 러너를 설치해야 할 수 있습니다. 자세한 내용은 수동으로 스텝 러너 설치를 참조하세요.

함수 사용#

run 키워드로 함수를 사용하는 GitLab CI/CD 잡을 구성합니다. 함수를 실행할 때는 잡에서 before_script, after_script, script를 사용할 수 없습니다.

스텝으로 함수 실행#

run 키워드는 실행할 스텝 목록을 수락합니다. 스텝은 목록에 정의된 순서대로 한 번에 하나씩 실행됩니다. 각 스텝에는 name, func 또는 script, 선택적으로 inputs와 env가 있습니다.

이름은 영숫자 문자와 밑줄만 포함해야 하며 숫자로 시작할 수 없습니다.

함수 호출#

스텝은 func 키워드로 함수 참조를 제공하여 함수를 호출할 수 있습니다. inputs 키워드로 함수에 입력값을 전달하고, env 키워드로 환경 값을 재정의합니다. func 값과 inputs 및 env의 키와 값에 표현식을 사용하세요.

함수는 호출된 함수가 작업 디렉토리를 재정의하지 않는 한 CI_PROJECT_DIR 디렉토리에서 실행됩니다.

예를 들어, 아래의 echo 함수를 실행하면 잡 로그에 Hi Sally! 메시지가 출력됩니다.

my-job:
  variables:
    FRIEND: "Sally"
  run:
    - name: say_hi
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
      inputs:
        message: "Hi ${{ vars.FRIEND }}!"

스크립트 실행#

스텝은 script 키워드로 스크립트를 호출할 수 있습니다. env를 사용하여 스크립트에 전달된 환경 변수는 셸에서 설정됩니다. 스크립트 스텝은 bash 셸을 사용하며, bash를 찾을 수 없는 경우 sh로 폴백합니다. 표현식은 script 값과 env의 키와 값에 사용할 수 있습니다. 스크립트 스텝은 CI_PROJECT_DIR 디렉토리에서 실행됩니다.

함수와 함께 사용자 정의 및 간단한 작업이 필요할 때 스크립트 스텝을 사용합니다. 내부적으로 함수는 스크립트를 함수 호출로 변환하고 스크립트를 입력값으로 전달합니다.

예를 들어, 다음 스크립트 스텝은 잡 로그에 Hi Sally! 메시지를 출력합니다:

my-job:
  variables:
    FRIEND: "Sally"
  run:
    - name: say_hi
      script: echo 'Hi ${{ vars.FRIEND }}!'

함수 참조#

함수는 파일 시스템이나 OCI 저장소에서 로드됩니다. Git 저장소에서 로드하는 것은 지원되지만 폐기됩니다.

OCI 저장소에서 로드#

히스토리

• GitLab Runner 18.9에서 도입됨.

OCI 저장소에서 함수를 로드하려면 레지스트리, 저장소, 버전(태그)을 제공합니다. 이 방법은 함수를 배포하고 사용하는 권장 방법입니다.

# prints 'Hi from GitLab Functions'
my-job:
  run:
    - name: echo
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
      inputs:
        message: "Hi from GitLab Functions"

함수가 루트에 없는 경우 이미지에서 하위 디렉토리와 파일 이름을 지정할 수도 있습니다:

# prints 'snoitcnuF baLtiG morf iH'
my-job:
  run:
    - name: echo
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1 reverse/func.yml
      inputs:
        message: "Hi from GitLab Functions"

함수 OCI 이미지는 여러 플랫폼을 지원합니다. 스텝 러너는 실행 중인 플랫폼과 일치하는 이미지를 다운로드합니다. 일치하는 이미지가 없으면 스텝이 실패합니다.

비공개 OCI 저장소에 인증하려면 Docker 구성 파일 형식의 값으로 DOCKER_AUTH_CONFIG 환경 변수를 설정합니다. 함수로서의 인증 작업 예시는 Docker Auth 함수를 참조하세요.

파일 시스템에서 로드#

상대 경로를 사용하여 파일 시스템에서 함수를 로드하려면 함수 참조를 .으로 시작합니다. 경로는 호출하는 함수의 디렉토리에 상대적입니다. 잡에서 직접 함수를 호출할 때 경로는 CI_PROJECT_DIR에 상대적입니다.

절대 경로를 사용하여 파일 시스템에서 함수를 로드하려면 함수 참조를 /로 시작합니다.

스텝이 실행될 때 경로가 함수 디렉토리가 됩니다. 함수 정의 YAML이 이 디렉토리에 있어야 합니다. 선택적으로, 표준이 아닌 경우 함수 정의 YAML 파일 이름을 제공합니다.

경로 구분자는 운영 체제에 관계없이 슬래시 /를 사용해야 합니다.

예를 들면:

• 상대 디렉토리에서 로드:

  - name: my_step
    func: ./path/to/my-function
  

• 절대 디렉토리에서 로드:

  - name: my_step
    func: /opt/gitlab-functions/my-function
  

• 사용자 정의 함수 정의 파일을 사용하여 로드:

  - name: my_step
    func: ./funcs/release/dry-run.yml
  

Git 저장소에서 로드 (폐기됨)#

Git 저장소에서 함수를 로드하려면 저장소의 URL과 리비전(커밋, 브랜치, 또는 태그)을 제공합니다. 저장소에 인증하려면 URL에 사용자 이름과 비밀번호를 추가합니다.

func에 텍스트로 Git 함수 참조를 제공할 때 함수는 steps 하위 디렉토리에 있어야 합니다. 긴 형식의 Git 함수 참조인 git을 사용할 때 함수는 dir 디렉토리에 있어야 합니다.

Git 저장소는 컴파일된 코드가 아닌 소스를 포함합니다. 가능하면 OCI 저장소에서 함수를 로드하세요.

예를 들면:

• 태그로 함수 지정:

  - name: my_step
    func: gitlab.com/funcs/my-git-repo@v1.0.0
  

• 브랜치로 함수 지정:

  - name: my_step
    func: gitlab.com/funcs/my-git-repo@main
  

• 디렉토리, 파일 이름, Git 커밋으로 함수 지정:

  - name: my_step
    func: gitlab.com/funcs/my-git-repo/-/reverse/my-func.yml@3c63f399ace12061db4b8b9a29f522f41a3d7f25
  

• 가져올 때 Git에 인증:

  - name: my_step
    func: gitlab-ci-token:${{ vars.CI_JOB_TOKEN }}@gitlab.com/funcs/my-git-repo@v2.0.0
  

steps 폴더 외부의 디렉토리나 파일을 지정하려면 확장된 func 구문을 사용합니다:

my-job:
  run:
    - name: my_step
      func:
        git:
          url: gitlab.com/funcs/my-git-repo
          rev: main
          dir: my-functions/sub-directory  # optional, defaults to the repository root
          file: my-func.yml                # optional, defaults to `func.yml`

표현식#

잡이 실행될 때까지 알 수 없는 값(이전 스텝의 출력, 잡 변수, 또는 계산된 값)이 필요할 때 표현식을 사용합니다.

표현식은 ${{ }} 구문을 사용하며 각 함수가 실행되기 전에 평가됩니다. 연산자, 데이터 구조, 내장 함수를 포함한 전체 표현식 언어 참조는 Moa 표현식 언어를 참조하세요.

표현식은 다음에서 사용할 수 있습니다:

• 입력값 값(inputs)
• 환경 변수 값(env)
• 함수 참조(func)
• 스크립트 내용(script)

사용 가능한 컨텍스트#

GitLab Functions를 사용할 때 다음 컨텍스트 변수를 사용합니다. 전체 컨텍스트 참조는 Moa 표현식 언어를 참조하세요.

예시#

• 이전 스텝의 출력 참조:

  my-job:
    run:
      - name: generate_rand
        func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/random:1
      - name: echo
        func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
        inputs:
          message: "The random value is: ${{ steps.generate_rand.outputs.random_value }}"
  

• 폴백 기본값이 있는 잡 변수 사용:

  run:
    - name: deploy
      func: ./deploy
      inputs:
        environment: ${{ vars.CI_COMMIT_REF_NAME == "main" && "production" || "staging" }}
  

환경 변수#

환경 변수는 두 가지 방법으로 스텝 간에 이동합니다: env로 설정하거나 함수를 통해 내보냅니다. 이 차이는 다른 범위를 가지기 때문에 중요합니다.

CI/CD 잡 변수는 환경 변수로 사용할 수 없습니다. 대신 ${{ vars.<name> }}을 사용하여 잡 변수에 접근합니다.

스텝에 환경 변수 설정#

스텝에 env 키워드를 사용하여 해당 스텝과 내부적으로 호출하는 모든 함수에 대한 환경 변수를 설정합니다. env로 설정된 변수는 환경에 이미 있는 모든 변수에 추가로 해당 스텝에서 사용할 수 있습니다. 변수가 이미 존재하는 경우 env로 설정된 값이 우선합니다. 이 방식으로 설정된 변수는 동일한 run 목록의 후속 스텝에서 사용할 수 없습니다.

run:
  - name: build
    func: ./build
    env:
      BUILD_TARGET: release   # available to build and its child steps only
  - name: test
    func: ./test              # BUILD_TARGET is not available here

env의 키와 값에 표현식을 사용하세요.

내보낸 환경 변수#

함수가 ${{ export_file }}에 쓸 때 쓴 변수는 run 목록의 모든 후속 스텝으로 내보내집니다. 함수는 나중 스텝과 상태를 공유하기 위해 이 방법을 사용합니다.

내보낸 변수는 표현식에서 env를 통해 사용할 수 있습니다:

run:
  - name: setup
    func: ./setup             # exports INSTALL_PATH during execution
  - name: build
    func: ./build
    inputs:
      path: ${{ env.INSTALL_PATH }}   # available because setup exported it

우선순위#

동일한 변수가 여러 위치에 설정된 경우 다음 순서가 적용됩니다(높은 것에서 낮은 순서):

1. 함수 정의(func.yml)에서 설정된 env
2. run 목록의 스텝에서 설정된 env
3. 이전에 실행된 스텝에서 내보냄
4. 러너에서 설정
5. OS 프로세스 환경에서 설정

문제 해결#

HTTPS URL에서 함수 가져오기#

tls: failed to verify certificate: x509: certificate signed by unknown authority와 같은 오류 메시지는 운영 체제가 함수를 호스팅하는 서버를 인식하거나 신뢰하지 않음을 나타냅니다.

일반적인 원인은 신뢰할 수 있는 루트 인증서가 설치되지 않은 Docker 이미지입니다. 컨테이너에 인증서를 설치하거나 잡 image에 포함하여 문제를 해결합니다.

함수를 가져오기 전에 의존성을 설치하기 위해 script 스텝을 사용할 수 있습니다:

ubuntu_job:
  image: ubuntu:24.04
  run:
    - name: install_certs
      script: apt update && apt install --assume-yes --no-install-recommends ca-certificates
    - name: echo_step
      func: registry.gitlab.com/user/my_functions/hello_world:1.0.0

나만의 함수 만들기#

함수를 만들려면 GitLab Function 만들기를 참조하세요.

함수 예시는 GitLab Functions 예시를 참조하세요.