GitLab Functions 예시

GitLab Functions 예시

GitLab Functions가 어떤 형태로 쓰이는지 감이 안 올 때, 실제 예시들을 따라가 보면 구조가 바로 이해돼요. 아래 예시들은 ca-certificates는 포함하지만 패키지 매니저나 셸이 없는 Google distroless 이미지를 사용합니다. 신뢰할 수 있는 CA 루트 인증서가 설치된 어떤 이미지든 사용할 수 있어요.

출처: 문서

본문

이 예시들은 ca-certificates를 포함하지만 패키지 매니저나 셸이 없는 Google distroless 이미지를 사용합니다. 신뢰할 수 있는 CA 루트 인증서가 설치된 어떤 이미지든 사용할 수 있어요.

메시지 echo

이후 단계에서 사용할 메시지를 출력합니다. 전체 소스 코드는 echo를 참고하세요.

Function 정의:

spec:
  inputs:
    message:
      type: string
      default: "Hello World!"
      description: "The message to print to stdout"
  outputs:
    message:
      type: string
---
exec:
  command:
    - ${{ func_dir }}/echo
    - --message
    - ${{ inputs.message }}
    - --output-file
    - ${{ output_file }}

사용 예시:

my-job:
  image: gcr.io/distroless/static-debian12
  run:
    - name: echo_hi
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
      inputs:
        message: "Hi, ${{ vars.GITLAB_USER_NAME }}"
    - name: echo_repeat
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
      inputs:
        message: "The echo_hi step said: ${{ steps.echo_hi.outputs.message }}"

출력:

Running step name=echo_hi
Hi, Zhang Wei
Running step name=echo_repeat
The echo_hi step said: Hi, Zhang Wei

랜덤 값 생성

이후 단계에서 사용할 랜덤 값을 생성합니다. 전체 소스 코드는 random을 참고하세요.

Function 정의:

spec:
  outputs:
    random_value:
      type: string
---
exec:
  command:
    - ${{ func_dir }}/random
    - --output-file
    - ${{ output_file }}

사용 예시:

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

출력:

Running step name=random
Running step name=print_random
The random value is: DVhV5vcd2BjDDtpV

JSON에서 필드 추출

jq를 실행해 JSON 입력을 필터링합니다. 전체 소스 코드는 jq를 참고하세요.

Function 정의:

spec:
  inputs:
    filter:
      type: string
      default: "."
    input:
      type: string
      default: "{}"
    input_file:
      type: string
      default: ""
  outputs:
    result:
      type: struct
---
exec:
  command:
    - ${{ func_dir }}/jq-wrapper
    - --func-dir
    - ${{ func_dir }}
    - --filter
    - ${{ inputs.filter }}
    - --input
    - ${{ inputs.input }}
    - --input-file
    - ${{ inputs.input_file }}
    - --output-file
    - ${{ output_file }}

사용 예시:

my-job:
  image: gcr.io/distroless/static-debian12
  run:
    - name: jq
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/jq:1
      inputs:
        input: |
          {"users":[
            {"name":"Alice","role":"admin"},
            {"name":"Bob","role":"viewer"},
            {"name":"Carol","role":"admin"}
          ]}
        filter: '[.users[] | select(.role == "admin") | .name]'
    - name: print_admins
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo:1
      inputs:
        message: "Admins: ${{ steps.jq.outputs.result.value }}"

출력:

Running step name=jq
Running step name=print_admins
Admins: ["Alice", "Carol"]

Docker에 인증

Docker 구성을 만들고 이를 환경 변수 DOCKER_AUTH_CONFIG의 값으로 추가해 이후 function에서 사용하게 합니다. 전체 소스 코드는 Docker Auth를 참고하세요.

Function 정의:

spec:
  inputs:
    registry:
      type: string
      default: ""
      description: "registry URL"
    username:
      type: string
      default: ""
      description: "username for auth type"
    password:
      type: string
      default: ""
      description: "password for auth type"
    helper_name:
      type: string
      default: ""
      description: "credential helper name"
    store_name:
      type: string
      default: ""
      description: "default credential store name"
    config_file:
      type: string
      default: ""
      description: "path to existing config.json (default: ~/.docker/config.json)"
  outputs:
    auth:
      type: struct
---
env:
  DOCKER_PASSWORD: ${{ inputs.password }}
exec:
  work_dir: ${{ func_dir }}
  command:
    - ${{ func_dir }}/docker-auth
    - --registry
    - ${{ inputs.registry }}
    - --username
    - ${{ inputs.username }}
    - --helper-name
    - ${{ inputs.helper_name }}
    - --store-name
    - ${{ inputs.store_name }}
    - --config
    - ${{ inputs.config_file }}
    - --output-file
    - ${{ output_file }}
    - --export-file
    - ${{ export_file }}

사용 예시:

build-image:
  image: gcr.io/distroless/static-debian12
  run:
    - name: auth_to_my_registry
      func: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/docker-auth:1
      inputs:
        registry: my.registry.com
        username: ${{ vars.MY_REGISTRY_USER }}
        password: ${{ vars.MY_REGISTRY_PASSWORD }}
    - name: my_func
      func: my.registry.com/my-function:latest  # requires auth to fetch an image

출력:

Running step name=auth_to_my_registry
added basic auth for registry my.registry.com
docker auth configuration complete
Running step name=my_func
...

더 알아보기

예시들을 보면 공통 패턴이 보여요. function은 spec으로 입력·출력을 선언하고, exec에서 ${{ func_dir }} 기반 바이너리와 ${{ inputs.* }}, ${{ output_file }}을 연결합니다. 사용 쪽에서는 func 참조와 inputs로 호출하고, 이전 단계 출력은 ${{ steps.<name>.outputs.* }}로 받아오죠. 이제 직접 function을 만들어 보려면 GitLab Function 만들기 문서로 이어가면 됩니다.