본문으로 건너뛰기

GitLab Runner 로컬 (Mac, Windows) 설치 및 구성 가이드

Docker 및 Docker Compose 설치​

macOS​

  1. 시스템 요구사항
  • macOS 10.14 이후 버전 (2021년 5월 현재 Mojave, Catalina, Big Sur)
  • 하드웨어는 2010 이후 모델
  • 최소 4 GB RAM
  1. Docker Desktop 설치
  • Docker Hub에서 Mac용 Docker Desktop을 다운로드받습니다.
  • 다운로드받은 Docker.dmg 파일을 더블 클릭하고 Docker 아이콘을 Applications 폴더에 드래그하여 설치를 진행합니다.
  • 설치가 완료되면 Applications 폴더에서 Docker.app을 더블 클릭하여 실행합니다.
  • Docker가 실행되면 Mac 상단 상태 바에서 고래 모양의 Docker 아이콘을 확인할 수 있습니다.
    photo | 인포그랩 GitLab | 인포그랩 GitLab
  1. Docker 설치 확인

Docker Desktop에는 Docker Engine, Docker CLI client, Docker Compose, Notary, Kubernetes, Credential Helper가 포함되어 있습니다.

  • Mac 상단 상태 바에서 Docker 아이콘을 클릭하고 "About Docker Desktop"을 선택하면 버전 정보를 확인할 수 있습니다.
    photo | 인포그랩 GitLab | 인포그랩 GitLab
  • 또는 터미널을 열고 아래와 같이 실행하여 버전 정보를 확인할 수 있습니다.
$ docker -v
Docker version 20.10.17, build 100c701
$ docker compose version
Docker Compose version v2.10.2
  • hello-world 이미지를 구동하여 Docker CE가 정상적으로 설치되었는지 확인합니다.
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
70f5ac315c5a: Pull complete
Digest: sha256:c2e23624975516c7e27b1b25be3682a8c6c4c0cea011b791ce98aa423b5040a0
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Windows​

  1. 시스템 요구사항
  • Windows 10 64-비트: Pro, Enterprise, or Education (Build 17134 or higher).
  • WSL 기능 사용 가능. 자세한 내용은 마이크로소프트 문서에서 확인 (Hyper-5 클라이언트, WSL2 중 선택하여 사용)
  • Windows 10에서 WSL2를 사용하기 위한 하드웨어 요구사항 :
  • 64 비트 프로세서와 Second Level Address Translation (SLAT)
  • 최소 4 GB RAM
  • 바이오스 설정에서 바이오스 수준의 하드웨어 기능이 사용 가능으로 설정. 더 많은 정보를 위해서 가상화를 참조
  1. Docker Desktop 설치
  • Docker Hub에서 Windows용 Docker Desktop을 다운로드 받습니다.
  • 다운받은 Docker Desktop Installer.exe를 실행하여 설치를 진행합니다.
  • 사용자가 관리자가 아니면 docker-users 그룹을 생성해야 합니다. Computer Management에서 Local Users and Groups > Groups > docker-users로 이동합니다. 오른쪽 버튼을 클릭하여 해당 사용자를 그룹에 추가합니다. 다시 로그인하여 변경점이 적용되었는지 확인합니다.
  • 설치가 완료되면 Docker Desktop은 자동으로 시작되지 않기 때문에, Docker Desktop을 실행해 줍니다.
    photo | 인포그랩 GitLab | 인포그랩 GitLab
  • Docker가 실행되면 Windows 오른쪽 하단에 상태 바에서 고래 모양의 Docker 아이콘을 확인할 수 있습니다.
    photo | 인포그랩 GitLab | 인포그랩 GitLab
  1. Docker 설치 확인
  • Windows 상태 파에서 Docker 아이콘을 오른쪽 클릭하고 "About Docker DeskTop"을 선택하면 버전 정보를 확인할 수 있습니다.
    photo | 인포그랩 GitLab | 인포그랩 GitLab
  • 또는 PowerShell과 같은 터미널을 열고 아래와 같이 실행하여 버전 정보를 확인할 수 있습니다.
C:\Users\user> docker -v
Docker version 24.0.2, build cb74dfc
PS C:\Users\user> docker-compose -v
Docker Compose version v2.18.1
  • hello-world 이미지를 구동하여 Docker CE가 정상적으로 설치되었는지 확인합니다.
C:\Users\user> docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b8dfde127a29: Pull complete
Digest: sha256:f2266cbfc127c960fd30e76b7c792dc23b588c0db76233517e1891a4e357d519
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

기초 사용법​

  • 컨테이너 확인
$ docker ps -a
CONTAINER ID   IMAGE         COMMAND    CREATED          STATUS                      PORTS     NAMES
81a04a70f855   hello-world   "/hello"   11 minutes ago   Exited (0) 11 minutes ago             hopeful_pascal
  • 컨테이너 삭제
$ docker rm 81a04a70f855
81a04a70f855
  • 이미지 확인
docker images
REPOSITORY    TAG       IMAGE ID       CREATED         SIZE
hello-world   latest    bf756fb1ae65   12 months ago   13.3kB
  • 이미지 삭제
$ docker rmi bf756fb1ae65
Untagged: hello-world:latest
Untagged: hello-world@sha256:1a523af650137b8accdaed439c17d684df61ee4d74feac151b5b337bd29e7eec
Deleted: sha256:bf756fb1ae65adf866bd8c456593cd24beb6a0a061dedf42b26a993176745f6b
Deleted: sha256:9c27e219663c25e0f28493790cc0b88bc973ba3b1686355f221c38a36978ac63

GitLab Runner 설치​

GitLab Runner는 GNU/Linux, macOS, FreeBSD 및 Windows에 설치하여 사용할 수 있습니다. 설치하는 방법에는 다음과 같이 세 가지가 있습니다.

  • Docker 사용
  • 바이너리를 수동으로 다운로드
  • rpm/deb 패키지용 리포지터리 사용

공식적으로 지원되는 GitLab Runner 바이너리는 다음 아키텍처에서 사용할 수 있습니다.

  • x86, AMD64, ARM64, ARM, s390x

공식 패키지는 다음 Linux 배포판에서 사용할 수 있습니다.

  • CentOS, Debian, Ubuntu, RHEL, Fedora, Mint

GitLab Runner는 공식적으로 다음 운영 체제를 지원합니다.

  • Linux, Windows, macOS, FreeBSD

GitLab Runner 설치 문서에서 다양한 설치 방법에 대한 정보를 찾을 수 있습니다.

본 가이드에서는 Docker를 사용하여 Runner를 설치하는 것을 설명합니다.

Docker Compose를 사용하여 GitLab Runner 설치 및 실행​

  • 로컬 PC의 원하는 디렉토리에서 아래와 같이 gitlab-runner 폴더와 docker-compose.yml 파일을 생성합니다. (최신 버전을 설치하려면 image: 'gitlab/gitlab-runner:latest'로 변경합니다.)

    $ mkdir gitlab-runner
    $ cd gitlab-runner
    $ cat <<EOF > docker-compose.yml
    version: "3"

    services:
      gitlab-runner:
        container_name: gitlab-runner
        image: 'gitlab/gitlab-runner:v16.0.2'
        restart: always
        volumes:
        - './config:/etc/gitlab-runner'
        - '/var/run/docker.sock:/var/run/docker.sock
    EOF
    $ ls -al
    total 8
    drwxr-xr-x   3 lucas  staff    96  6 22 15:56 .
    drwxr-xr-x  60 lucas  staff  1920  6 22 15:52 ..
    -rw-r--r--   1 lucas  staff   202  6 22 15:56 docker-compose.yml

  • gitlab-runner 컨테이너를 실행합니다.

    $ docker compose up -d
    [+] Running 4/4
    ⠿ gitlab-runner Pulled    20.8s
      ⠿ 8659cf1709ef Pull complete 2.6s
      ⠿ 791ef80cc148 Pull complete 17.3s
      ⠿ 8c0f208d57ba Pull complete 17.3s
    [+] Running 2/2
    ⠿ Network gitlab-runner_default  Created 0.1s
    ⠿ Container gitlab-runner        Started 0.9s

    $ docker-compose ps -a
    NAME                COMMAND                  SERVICE             STATUS              PORTS    --------------------------------------------------------------
    gitlab-runner       "/usr/bin/dumb-init …"   gitlab-runner       running

    $ docker container ls
    CONTAINER ID   IMAGE                          COMMAND                  CREATED         STATUS         PORTS     NAMES
    f7a80756eeb3   gitlab/gitlab-runner:v16.0.2   "/usr/bin/dumb-init …"   2 minutes ago   Up 2 minutes                                          gitlab-runner

GitLab Runner 등록​

GitLab Runner 등록 방식은 15.10부터 변경되었습니다. 기존에 사용되던 등록 토큰을 사용하는 방식은 더 이상 사용되지 않습니다. GitLab Runner 등록 문서를 참조하세요.

GitLab UI에는 액세스할 사용자에 따라 세 가지 유형의 러너가 있습니다.

  • 공유 러너는 GitLab 인스턴스의 모든 그룹 및 프로젝트에서 사용할 수 있습니다. (Admin Area의 Overview > Runners)
  • 그룹 러너는 그룹의 모든 프로젝트와 하위 그룹에서 사용할 수 있습니다. (그룹의 Settings > CI/CD > Runners 섹션)
  • 특정 러너는 특정 프로젝트와 연결됩니다. 일반적으로 특정 러너는 한 번에 하나의 프로젝트에 사용됩니다. (프로젝트의 Settings > CI/CD > Runners 섹션)

본 가이드에서는 특정 러너(Specific runner)를 등록하는 방법을 설명합니다. (해당 프로젝트의 maintainer 권한이 필요합니다.)

  • GitLab의 러너를 등록할 프로젝트로 이동하여 사이드바에서 Settings > CI/CD > Runners 세션으로 이동합니다.
  • New Project runner - Linux 항목을 선택합니다.
  • Run untagged jobs 체크박스 활성화 - Create Runner 선택하면 Step1에 다음과 같은 메시지가 표시됩니다.
$ gitlab-runner register
  --url https://gitlab.com
  --token glrt-1234567890abcdefg
  • 터미널에서 아래 명령을 실행하여 gitlab-runner 컨네이너에 대화형(interactive) bash 셸을 실행합니다.
docker-compose exec gitlab-runner bash
  • 위에서 생성한 gitlab-runner register --url https://gitlab.com --token glrt-1234567890abcdefg 명령을 실행하고 지침에 따라 아래 항목을 입력합니다.
    • Enter the GitLab instance URL : --url 정보(gitlab.com)가 자동으로 세팅되어 Enter 키를 누릅니다.
    • Enter a name for runner : 러너에 대한 이름을 입력하고 Enter 키를 누릅니다. (예: specific-runner-1)
    • Enter an executor : docker을 입력하고 Enter 키를 누릅니다.
    • Enter the default Docker image : alpine:latest을 입력하고 Enter 키를 누릅니다.
root@d77a1e731b96:/# gitlab-runner register  --url https://gitlab.com  --token glrt-1234567890abcdefg
Runtime platform                                    arch=arm64 os=linux pid=28 revision=b72e108d version=16.1.0
Running in system-mode.

Enter the GitLab instance URL (for example, https://gitlab.com/):
[https://gitlab.com]:
Verifying runner... is valid                        runner=12345678
Enter a name for the runner. This is stored only in the local config.toml file:
[d77a1e731b96]: specific-runner-1
Enter an executor: parallels, virtualbox, ssh, docker-autoscaler, docker+machine, instance, custom, docker, docker-windows, shell, kubernetes:
docker
Enter the default Docker image (for example, ruby:2.7):
alpine:latest
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"
  • GitLab UI를 새로고침하면 등록된 러너가 목록에 나타납니다.

GitLab Runner 구성​

GitLab Runner 및 등록된 개별 Runner의 동작을 변경할 수 있습니다.

GitLab Runner의 구성을 변경하려면 config.toml 파일을 수정해야 합니다.

대부분의 옵션을 변경할 때 GitLab Runner를 다시 시작할 필요가 없습니다. 여기에는 listen_address를 제외한 [[runners]] 섹션의 파라미터와 글로벌 섹션의 대부분의 파라미터가 포함됩니다.

GitLab Runner는 3초마다 구성 수정사항을 확인하고 필요한 경우 다시 로드합니다.

Job 동시성(concurrency) 설정

GitLab Runner가 동시에 여러 Job을 실행할 수 있도록 적절하게 concurrent를 수정합니다.

예를 들어, 4vCPU/16GiB인 경우 concurrent = 4로 설정합니다.

GitLab.com의 자동 확장(Auto-scaling) Shared Runner는 단일 작업이 1 vCPU와 3.75GiB를 사용하여 단일 인스턴스에서 실행되도록 구성됩니다.

Docker 특권(privileged) 모드 설정

아래 CI 파이프라인(.gitlab-ci.yml)과 같이, Docker-in-Docker 컨테이너를 사용하여 docker build와 같은 스크립트를 실행하기 위해서는 특권 모드(privileged mode) 설정이 필요합니다.

image: docker:git
services:
  - docker:dind

build:
  script:
    - docker build -t my-image .
    - docker push my-image

[runners.docker] 섹션에서 privileged = true로 설정합니다.

위에서 언급한 Runner 옵션을 수정하려면 Runner 작업 디렉토리(예: /data/gitlab-runner)에서 아래 명령을 실행하고 수정합니다.

sudo vi config/config.toml

수정한 config.toml 파일은 아래와 유사합니다.

concurrent = 4
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "shared-runner-1"
  url = "https://gitlab.com/"
  token = "3ixsKUSBDcmvV4vxDJCZ"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0