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.2, build 2291f61
$ docker-compose -v
docker-compose version 1.27.4, build 40524192
  • hello-world 이미지를 구동하여 Docker CE가 정상적으로 설치되었는지 확인합니다.
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
0e03bdcc26d7: Pull complete
Digest: sha256:1a523af650137b8accdaed439c17d684df61ee4d74feac151b5b337bd29e7eec
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/

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 20.10.5, build 55c4c88
PS C:\Users\user> docker-compose -v
docker-compose version 1.29.0, build 07737305
  • 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
    gitlab-runner:
    container_name: gitlab-runner
    image: 'gitlab/gitlab-runner:v13.7.0'
    restart: always
    volumes:
    - './config:/etc/gitlab-runner'
    - '/var/run/docker.sock:/var/run/docker.sock'
    EOF
    $ ls -al
    total 8
    drwxr-xr-x 3 jason staff 96 1 11 16:53 .
    drwxr-xr-x 10 jason staff 320 1 11 16:21 ..
    -rw-r--r-- 1 jason staff 170 1 11 16:53 docker-compose.yml
  • gitlab-runner 컨테이너를 실행합니다.

    $ docker-compose up -d
    Pulling gitlab-runner (gitlab/gitlab-runner:v13.7.0)...
    v13.7.0: Pulling from gitlab/gitlab-runner
    da7391352a9b: Pull complete
    14428a6d4bcd: Pull complete
    2c2d948710f2: Pull complete
    d23b1723c41a: Pull complete
    89529a82a98d: Pull complete
    a70bbbdfc98d: Pull complete
    45d87f0953b1: Pull complete
    Digest: sha256:c8a6ef3ad234a6da2e48ec986a1f4f4a3f16a1e817214d48aecc09745131deb4
    Status: Downloaded newer image for gitlab/gitlab-runner:v13.7.0
    Creating gitlab-runner ... done
    $ docker-compose ps -a
    Name Command State Ports
    --------------------------------------------------------------
    gitlab-runner /usr/bin/dumb-init /entryp ... Up
    $ docker container ls
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
    3130953c8ea7 gitlab/gitlab-runner:v13.7.0 "/usr/bin/dumb-init …" 2 minutes ago Up 2 minutes gitlab-runner

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 세션으로 이동합니다.
  • 터미널에서 아래 명령을 실행하여 gitlab-runner 컨네이너에 대화형(interactive) bash 셸을 실행합니다.
docker-compose exec gitlab-runner bash
  • gitlab-runner register 명령을 실행하고 지침에 따라 아래 항목을 입력합니다.
    • Enter the GitLab instance URL : GitLab UI에서 Copy URL 아이콘을 클릭하여 클립보드에 복사한 후 붙여넣고 Enter 키를 누룹니다.
    • Enter the registration token : GitLab UI에서 Copy token 아이콘을 클릭하여 클립보드에 복사한 후 붙여넣고 Enter 키를 누룹니다.
    • Enter a description for the runner : 러너에 대한 설명을 입력하고 Enter 키를 누룹니다. (예: specific-runner-1)
    • Enter tags for the runner : 아무것도 입력하지 않고 Enter 키를 누룹니다.
    • Enter an executor : docker을 입력하고 Enter 키를 누룹니다.
    • Enter the default Docker image : alpine:latest을 입력하고 Enter 키를 누룹니다.
root@4f99bda8cc66:/# gitlab-runner register
Runtime platform arch=amd64 os=linux pid=37 revision=7f7a4bb0 version=13.11.0
Running in system-mode.
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.com/
Enter the registration token:
3ixsKUSBDcmvV4vxDJCZ
Enter a description for the runner:
[4f99bda8cc66]: specific-runner-1
Enter tags for the runner (comma-separated):
Registering runner... succeeded runner=m5zs6LEP
Enter an executor: docker-ssh, shell, ssh, docker-ssh+machine, kubernetes, custom, docker, parallels, virtualbox, docker+machine:
docker
Enter the default Docker image (for example, ruby:2.6):
alpine:latest
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
  • 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