컨테이너에서 GitLab Runner 실행

요약

Docker 컨테이너에서 GitLab Runner를 실행하여 CI/CD 작업을 실행할 수 있습니다. GitLab Runner Docker 이미지는 Ubuntu 또는 Alpine Linux를 기반으로 사용합니다. gitlab-runner 명령은 Docker 컨테이너에서 실행됩니다.

Docker 컨테이너에서 GitLab Runner를 실행하여 CI/CD 작업을 실행할 수 있습니다. GitLab Runner Docker 이미지에는 다음에 필요한 모든 종속성이 포함되어 있습니다:

GitLab Runner 실행
컨테이너에서 CI/CD 작업 실행

GitLab Runner Docker 이미지는 Ubuntu 또는 Alpine Linux를 기반으로 사용합니다. 이미지들은 호스트에서 직접 GitLab Runner를 설치하는 것과 유사하게 표준 gitlab-runner 명령을 래핑합니다.

gitlab-runner 명령은 Docker 컨테이너에서 실행됩니다. 이 설정은 Docker 데몬에 대한 완전한 제어를 각 GitLab Runner 컨테이너에 위임합니다. 그 결과 다른 페이로드도 실행하는 Docker 데몬 내에서 GitLab Runner를 실행하면 격리 보장이 깨집니다.

이 설정에서 모든 GitLab Runner 명령에는 다음과 같은 docker run 동등 명령이 있습니다:

러너 명령: gitlab-runner <runner command and options...>
Docker 명령: docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

예를 들어 GitLab Runner의 최상위 도움말 정보를 가져오려면 명령의 gitlab-runner 부분을 docker run [docker options] gitlab/gitlab-runner로 교체합니다:

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   18.10.1 (3b43bf9f)

(...)

Docker Engine 버전 호환성#

Docker Engine과 GitLab Runner 컨테이너 이미지의 버전은 일치할 필요가 없습니다. GitLab Runner 이미지는 하위 및 상위 호환이 됩니다. 최신 기능과 보안 업데이트를 보유하려면 항상 최신 안정 Docker Engine 버전을 사용해야 합니다.

Docker 이미지 설치 및 컨테이너 시작#

사전 요구 사항:

Docker를 설치했습니다.
GitLab Runner의 일반적인 문제에 대해 알아보기 위해 FAQ를 읽었습니다.

docker pull gitlab/gitlab-runner:<version-tag> 명령을 사용하여 gitlab-runner Docker 이미지를 다운로드합니다.

사용 가능한 버전 태그 목록은 GitLab Runner 태그를 참조하세요.
docker run -d [options] <image-uri> <runner-command> 명령을 사용하여 gitlab-runner Docker 이미지를 실행합니다.
Docker 컨테이너에서 gitlab-runner를 실행할 때 컨테이너를 재시작할 때 구성이 손실되지 않도록 합니다. 구성을 저장하기 위한 영구 볼륨을 마운트합니다. 볼륨은 다음 위치에 마운트할 수 있습니다:
- 로컬 시스템 볼륨
- Docker 볼륨
선택 사항. session_server를 사용하는 경우 docker run 명령에 -p 8093:8093을 추가하여 포트 8093을 노출합니다.
선택 사항. 자동 스케일링에 Docker Machine 실행기를 사용하려면 docker run 명령에 볼륨 마운트를 추가하여 Docker Machine 스토리지 경로(/root/.docker/machine)를 마운트합니다:
- 시스템 볼륨 마운트의 경우 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine을 추가합니다.
- Docker 명명된 볼륨의 경우 -v docker-machine-config:/root/.docker/machine을 추가합니다.
새 러너를 등록합니다. GitLab Runner 컨테이너는 작업을 수행하기 위해 등록되어야 합니다.

일부 사용 가능한 구성 옵션:

--env TZ= 플래그로 컨테이너의 시간대를 설정합니다. 사용 가능한 시간대 목록을 참조하세요.
redhat/ubi9-micro 기반의 FIPS 호환 GitLab Runner 이미지의 경우 gitlab/gitlab-runner:ubi-fips 태그를 사용합니다.
신뢰할 수 있는 SSL 서버 인증서를 설치합니다.

로컬 시스템 볼륨에서#

구성 볼륨 및 gitlab-runner 컨테이너에 마운트된 다른 리소스에 로컬 시스템을 사용하려면:

선택 사항. MacOS 시스템에서 /srv는 기본적으로 존재하지 않습니다. 설정을 위해 /private/srv 또는 다른 프라이빗 디렉토리를 만듭니다.

필요에 맞게 수정하여 이 명령을 실행합니다:

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

Docker 볼륨에서#

사용자 정의 데이터 볼륨을 마운트하기 위해 구성 컨테이너를 사용하려면:

Docker 볼륨을 만듭니다:

docker volume create gitlab-runner-config

방금 만든 볼륨을 사용하여 GitLab Runner 컨테이너를 시작합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

러너 구성 업데이트#

config.toml에서 러너 구성을 변경한 후 docker stop과 docker run으로 컨테이너를 재시작하여 변경 사항을 적용합니다.

러너 버전 업그레이드#

사전 요구 사항:

원래 했던 것과 동일한 방법으로 데이터 볼륨을 마운트해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 -v gitlab-runner-config:/etc/gitlab-runner).

최신 버전(또는 특정 태그)을 pull합니다:
```
docker pull gitlab/gitlab-runner:latest
```

기존 컨테이너를 중지하고 제거합니다:

docker stop gitlab-runner && docker rm gitlab-runner

원래 했던 것처럼 컨테이너를 시작합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

러너 로그 보기#

로그 파일 위치는 러너를 시작하는 방법에 따라 다릅니다. 다음과 같이 시작하면:

로컬에 설치된 바이너리 또는 Docker 컨테이너에서 포어그라운드 작업으로 시작하면 로그가 stdout에 출력됩니다.
systemd와 같은 시스템 서비스로 시작하면 로그가 Syslog와 같은 시스템 로깅 메커니즘에서 사용 가능합니다.
Docker 기반 서비스로 시작하면 docker logs 명령을 사용합니다. gitlab-runner ... 명령이 컨테이너의 기본 프로세스입니다.

예를 들어 이 명령으로 컨테이너를 시작하면 이름이 gitlab-runner로 설정됩니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

로그를 보려면 gitlab-runner를 컨테이너 이름으로 교체하여 이 명령을 실행합니다:

docker logs gitlab-runner

컨테이너 로그 처리에 대한 자세한 내용은 Docker 문서의 docker container logs를 참조하세요.

신뢰할 수 있는 SSL 서버 인증서 설치#

GitLab CI/CD 서버가 자체 서명 SSL 인증서를 사용하는 경우 러너 컨테이너가 GitLab CI 서버 인증서를 신뢰하는지 확인합니다. 이렇게 하면 통신 오류를 방지할 수 있습니다.

사전 요구 사항:

ca.crt 파일에 GitLab Runner가 신뢰하려는 모든 서버의 루트 인증서가 포함되어야 합니다.

선택 사항. gitlab/gitlab-runner 이미지는 /etc/gitlab-runner/certs/ca.crt에서 신뢰할 수 있는 SSL 인증서를 찾습니다. 이 동작을 변경하려면 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 구성 옵션을 사용합니다.
데이터 볼륨(또는 컨테이너)의 certs 디렉토리에 ca.crt 파일을 복사합니다.
선택 사항. 컨테이너가 이미 실행 중인 경우 시작 시 ca.crt 파일을 가져오기 위해 재시작합니다.

Docker 이미지#

GitLab Runner 18.8.0에서 Alpine 기반 Docker 이미지는 Alpine 3.21을 사용합니다. 다음 멀티 플랫폼 Docker 이미지를 사용할 수 있습니다:

gitlab/gitlab-runner:latest Ubuntu 기반, 약 800 MB.
gitlab/gitlab-runner:alpine Alpine 기반, 약 460 MB.

Ubuntu 및 Alpine 이미지 모두에 대한 가능한 빌드 지침은 GitLab Runner 소스를 참조하세요.

러너 Docker 이미지 만들기#

GitLab 리포지터리에서 업데이트가 제공되기 전에 이미지의 운영 체제를 업그레이드할 수 있습니다.

사전 요구 사항:

docker-machine 종속성이 포함되지 않은 IBM Z 이미지를 사용하지 않아야 합니다. 이 이미지는 Linux s390x 또는 Linux ppc64le 플랫폼에서 유지 관리되지 않습니다. 현재 상태는 이슈 26551을 참조하세요.

최신 Alpine 버전의 gitlab-runner Docker 이미지를 빌드하려면:

alpine-upgrade/Dockerfile을 만듭니다.

ARG GITLAB_RUNNER_IMAGE_TYPE
ARG GITLAB_RUNNER_IMAGE_TAG
FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}

RUN apk update
RUN apk upgrade

업그레이드된 gitlab-runner 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \
GITLAB_RUNNER_IMAGE_TAG=alpine-v17.9.1 \
docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
  -f alpine-upgrade/Dockerfile alpine-upgrade

업그레이드된 gitlab-runner-helper 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \
GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.9.1 \
docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
  -f alpine-upgrade/Dockerfile alpine-upgrade

컨테이너에서 SELinux 사용#

CentOS, Red Hat, Fedora와 같은 일부 배포판은 기본 시스템 보안을 강화하기 위해 기본적으로 SELinux(Security-Enhanced Linux)를 사용합니다.

이 구성에 주의하세요.

사전 요구 사항:

컨테이너에서 빌드를 실행하기 위해 Docker 실행기를 사용하려면 러너에 /var/run/docker.sock에 대한 액세스가 필요합니다.
강제 모드에서 SELinux를 사용하는 경우 러너가 /var/run/docker.sock에 액세스할 때 Permission denied 오류를 방지하기 위해 selinux-dockersock을 설치합니다.

호스트에 영구 디렉토리를 만듭니다: mkdir -p /srv/gitlab-runner/config.

볼륨에 :Z를 사용하여 Docker를 실행합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
  gitlab/gitlab-runner:latest

컨테이너에서 GitLab Runner 실행

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-05-22

요약

GitLab Runner 실행
컨테이너에서 CI/CD 작업 실행

이 설정에서 모든 GitLab Runner 명령에는 다음과 같은 docker run 동등 명령이 있습니다:

러너 명령: gitlab-runner <runner command and options...>
Docker 명령: docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

예를 들어 GitLab Runner의 최상위 도움말 정보를 가져오려면 명령의 gitlab-runner 부분을 docker run [docker options] gitlab/gitlab-runner로 교체합니다:

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   18.10.1 (3b43bf9f)

(...)

Docker Engine 버전 호환성#

Docker 이미지 설치 및 컨테이너 시작#

사전 요구 사항:

Docker를 설치했습니다.
GitLab Runner의 일반적인 문제에 대해 알아보기 위해 FAQ를 읽었습니다.

docker pull gitlab/gitlab-runner:<version-tag> 명령을 사용하여 gitlab-runner Docker 이미지를 다운로드합니다.

사용 가능한 버전 태그 목록은 GitLab Runner 태그를 참조하세요.
docker run -d [options] <image-uri> <runner-command> 명령을 사용하여 gitlab-runner Docker 이미지를 실행합니다.
Docker 컨테이너에서 gitlab-runner를 실행할 때 컨테이너를 재시작할 때 구성이 손실되지 않도록 합니다. 구성을 저장하기 위한 영구 볼륨을 마운트합니다. 볼륨은 다음 위치에 마운트할 수 있습니다:
- 로컬 시스템 볼륨
- Docker 볼륨
선택 사항. session_server를 사용하는 경우 docker run 명령에 -p 8093:8093을 추가하여 포트 8093을 노출합니다.
선택 사항. 자동 스케일링에 Docker Machine 실행기를 사용하려면 docker run 명령에 볼륨 마운트를 추가하여 Docker Machine 스토리지 경로(/root/.docker/machine)를 마운트합니다:
- 시스템 볼륨 마운트의 경우 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine을 추가합니다.
- Docker 명명된 볼륨의 경우 -v docker-machine-config:/root/.docker/machine을 추가합니다.
새 러너를 등록합니다. GitLab Runner 컨테이너는 작업을 수행하기 위해 등록되어야 합니다.

일부 사용 가능한 구성 옵션:

--env TZ= 플래그로 컨테이너의 시간대를 설정합니다. 사용 가능한 시간대 목록을 참조하세요.
redhat/ubi9-micro 기반의 FIPS 호환 GitLab Runner 이미지의 경우 gitlab/gitlab-runner:ubi-fips 태그를 사용합니다.
신뢰할 수 있는 SSL 서버 인증서를 설치합니다.

로컬 시스템 볼륨에서#

구성 볼륨 및 gitlab-runner 컨테이너에 마운트된 다른 리소스에 로컬 시스템을 사용하려면:

선택 사항. MacOS 시스템에서 /srv는 기본적으로 존재하지 않습니다. 설정을 위해 /private/srv 또는 다른 프라이빗 디렉토리를 만듭니다.

필요에 맞게 수정하여 이 명령을 실행합니다:

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

Docker 볼륨에서#

사용자 정의 데이터 볼륨을 마운트하기 위해 구성 컨테이너를 사용하려면:

Docker 볼륨을 만듭니다:

docker volume create gitlab-runner-config

방금 만든 볼륨을 사용하여 GitLab Runner 컨테이너를 시작합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

러너 구성 업데이트#

config.toml에서 러너 구성을 변경한 후 docker stop과 docker run으로 컨테이너를 재시작하여 변경 사항을 적용합니다.

러너 버전 업그레이드#

사전 요구 사항:

원래 했던 것과 동일한 방법으로 데이터 볼륨을 마운트해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 -v gitlab-runner-config:/etc/gitlab-runner).

최신 버전(또는 특정 태그)을 pull합니다:
```
docker pull gitlab/gitlab-runner:latest
```

기존 컨테이너를 중지하고 제거합니다:

docker stop gitlab-runner && docker rm gitlab-runner

원래 했던 것처럼 컨테이너를 시작합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

러너 로그 보기#

로그 파일 위치는 러너를 시작하는 방법에 따라 다릅니다. 다음과 같이 시작하면:

로컬에 설치된 바이너리 또는 Docker 컨테이너에서 포어그라운드 작업으로 시작하면 로그가 stdout에 출력됩니다.
systemd와 같은 시스템 서비스로 시작하면 로그가 Syslog와 같은 시스템 로깅 메커니즘에서 사용 가능합니다.
Docker 기반 서비스로 시작하면 docker logs 명령을 사용합니다. gitlab-runner ... 명령이 컨테이너의 기본 프로세스입니다.

예를 들어 이 명령으로 컨테이너를 시작하면 이름이 gitlab-runner로 설정됩니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

로그를 보려면 gitlab-runner를 컨테이너 이름으로 교체하여 이 명령을 실행합니다:

docker logs gitlab-runner

컨테이너 로그 처리에 대한 자세한 내용은 Docker 문서의 docker container logs를 참조하세요.

신뢰할 수 있는 SSL 서버 인증서 설치#

사전 요구 사항:

ca.crt 파일에 GitLab Runner가 신뢰하려는 모든 서버의 루트 인증서가 포함되어야 합니다.

선택 사항. gitlab/gitlab-runner 이미지는 /etc/gitlab-runner/certs/ca.crt에서 신뢰할 수 있는 SSL 인증서를 찾습니다. 이 동작을 변경하려면 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 구성 옵션을 사용합니다.
데이터 볼륨(또는 컨테이너)의 certs 디렉토리에 ca.crt 파일을 복사합니다.
선택 사항. 컨테이너가 이미 실행 중인 경우 시작 시 ca.crt 파일을 가져오기 위해 재시작합니다.

Docker 이미지#

GitLab Runner 18.8.0에서 Alpine 기반 Docker 이미지는 Alpine 3.21을 사용합니다. 다음 멀티 플랫폼 Docker 이미지를 사용할 수 있습니다:

gitlab/gitlab-runner:latest Ubuntu 기반, 약 800 MB.
gitlab/gitlab-runner:alpine Alpine 기반, 약 460 MB.

Ubuntu 및 Alpine 이미지 모두에 대한 가능한 빌드 지침은 GitLab Runner 소스를 참조하세요.

러너 Docker 이미지 만들기#

GitLab 리포지터리에서 업데이트가 제공되기 전에 이미지의 운영 체제를 업그레이드할 수 있습니다.

사전 요구 사항:

docker-machine 종속성이 포함되지 않은 IBM Z 이미지를 사용하지 않아야 합니다. 이 이미지는 Linux s390x 또는 Linux ppc64le 플랫폼에서 유지 관리되지 않습니다. 현재 상태는 이슈 26551을 참조하세요.

최신 Alpine 버전의 gitlab-runner Docker 이미지를 빌드하려면:

alpine-upgrade/Dockerfile을 만듭니다.

ARG GITLAB_RUNNER_IMAGE_TYPE
ARG GITLAB_RUNNER_IMAGE_TAG
FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}

RUN apk update
RUN apk upgrade

업그레이드된 gitlab-runner 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \
GITLAB_RUNNER_IMAGE_TAG=alpine-v17.9.1 \
docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
  -f alpine-upgrade/Dockerfile alpine-upgrade

업그레이드된 gitlab-runner-helper 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \
GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.9.1 \
docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
  --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
  --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
  -f alpine-upgrade/Dockerfile alpine-upgrade

컨테이너에서 SELinux 사용#

CentOS, Red Hat, Fedora와 같은 일부 배포판은 기본 시스템 보안을 강화하기 위해 기본적으로 SELinux(Security-Enhanced Linux)를 사용합니다.

이 구성에 주의하세요.

사전 요구 사항:

컨테이너에서 빌드를 실행하기 위해 Docker 실행기를 사용하려면 러너에 /var/run/docker.sock에 대한 액세스가 필요합니다.
강제 모드에서 SELinux를 사용하는 경우 러너가 /var/run/docker.sock에 액세스할 때 Permission denied 오류를 방지하기 위해 selinux-dockersock을 설치합니다.

호스트에 영구 디렉토리를 만듭니다: mkdir -p /srv/gitlab-runner/config.

볼륨에 :Z를 사용하여 Docker를 실행합니다:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
  gitlab/gitlab-runner:latest