개요

Container 환경에서 gitlab-runner를 생성하고 GitLab에 등록하는 절차를 정리합니다. Docker로 gitlab-runner 컨테이너를 실행한 후, 컨테이너 내부에서 gitlab-runner register 명령으로 GitLab 서버와 연결합니다. 등록 완료 후 CI/CD 파이프라인이 해당 runner에서 실행됩니다.

Container 환경에서 gitlab-runner를 생성하고 GitLab에 등록 하는 절차에 관한 내용 입니다.

gitlab-runner 컨테이너 생성

gitlab-runner 컨테이너는 Docker 소켓(/var/run/docker.sock)을 마운트하여 실행합니다. 이를 통해 gitlab-runner 컨테이너가 호스트의 Docker 데몬에 직접 명령을 전달할 수 있습니다. CI/CD 파이프라인에서 Docker 이미지 빌드나 컨테이너 실행이 필요할 때 이 소켓 마운트가 핵심 역할을 합니다. --restart always 옵션으로 서버 재부팅 시에도 gitlab-runner가 자동으로 기동됩니다.

<admin-user>@<runner-server>:~$ docker run --detach \
> --name gitlab-runner \
> --restart always \
> --volume /srv/gitlab-runner/config:/etc/gitlab-runner \
> --volume /var/run/docker.sock:/var/run/docker.sock \
> gitlab/gitlab-runner:latest
Unable to find image 'gitlab/gitlab-runner:latest' locally
latest: Pulling from gitlab/gitlab-runner
d9802f032d67: Pull complete
d71acd29818d: Pull complete
2df872e9a082: Pull complete
Digest: sha256:c7e23480375fca186743d8fbf6eff3b682da48b70a9d2980ce89863571fb6fa8
Status: Downloaded newer image for gitlab/gitlab-runner:latest
4f0eb91d3bd9cdc008545ab664e5746de3eefff6f92fce380dd4b29d290c8154
<admin-user>@<runner-server>:~$ docker ps -a
CONTAINER ID   IMAGE                         COMMAND                  CREATED              STATUS              PORTS     NAMES
4f0eb91d3bd9   gitlab/gitlab-runner:latest   "/usr/bin/dumb-init …"   About a minute ago   Up About a minute             gitlab-runner

Docker Executor 동작 방식

gitlab-runner의 executor 종류는 Shell, Docker, Kubernetes 등 다양합니다. 이 포스트에서는 Docker executor를 사용합니다. Docker executor는 각 CI/CD Job을 독립된 Docker 컨테이너 안에서 실행하므로, Job 간 의존성 오염 없이 클린한 실행 환경을 보장합니다. --docker-image docker:latest는 Job 실행에 사용할 기본 이미지이며, 개별 Job의 .gitlab-ci.yml에서 image:를 지정하면 이를 덮어쓸 수 있습니다.

Docker-in-Docker(DinD) 방식으로 파이프라인 내부에서 Docker build를 실행하려면 --docker-volumes /var/run/docker.sock:/var/run/docker.sock를 함께 전달하여 호스트 소켓을 컨테이너에 공유합니다. 이 방식은 격리성보다 편의성을 우선할 때 적합합니다.

등록 token 확인

GitLab 프로젝트(또는 그룹)의 Settings > CI/CD > Runners에서 등록에 필요한 token을 확인합니다.

gitlab-runner GitLab 등록

컨테이너 내부에서 gitlab-runner register 명령으로 GitLab 서버 URL, token, executor, Docker image를 지정하여 runner를 등록합니다.

<admin-user>@<runner-server>:~$ docker container exec -it gitlab-runner bash
root@4f0eb91d3bd9:/# gitlab-runner register -n \
> --url http://x.x.x.x:8081/ \
> --registration-token <gitlab token> \
> --description gitlab-runner \
> --executor docker \
> --docker-image docker:latest \
> --docker-volumes /var/run/docker.sock:/var/run/docker.sock
Runtime platform                                    arch=amd64 os=linux pid=24 revision=374d34fd version=17.6.0
Running in system-mode.

WARNING: Support for registration tokens and runner parameters in the 'register' command has been deprecated in GitLab Runner 15.6 and will be replaced with support for authentication tokens. For more information, see https://docs.gitlab.com/ee/ci/runners/new_creation_workflow
Registering runner... succeeded                     runner=JdXqqyrV
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 프로젝트의 Settings > CI/CD > Runners에서 runner가 정상 등록되었는지 확인합니다. 등록된 runner는 초록색 원(●)으로 표시되며, 이름 아래에 runner ID와 마지막 통신 시간이 표시됩니다. runner 상태가 회색 원으로 표시된다면 gitlab-runner 컨테이너가 실행 중이지 않거나 GitLab 서버와의 네트워크 연결에 문제가 있는 것입니다.

등록 완료 후 프로젝트에 .gitlab-ci.yml 파일을 추가하면 GitLab이 자동으로 파이프라인을 트리거하고 등록된 runner에 Job을 할당합니다. runner가 Specific 타입으로 등록된 경우 해당 프로젝트에서만 동작하며, Group 또는 Shared runner로 등록하면 더 넓은 범위에서 재사용할 수 있습니다.

참고

• GitLab CE 설치 — Ubuntu 22.04 자가 관리형 GitLab 17.6.2 구성
• Kubernetes Cluster Upgrade — kubeadm 단계별 업그레이드 절차

참고 문서: GitLab Runner Docker 설치 공식 문서 · GitLab Runner 등록 공식 문서