GitLab Runner

요약

GitLab Runner는 GitLab CI/CD와 함께 작동하여 파이프라인에서 작업을 실행하는 애플리케이션입니다. 개발자가 GitLab에 코드를 푸시하면 .gitlab-ci.yml 파일에 자동화된 작업을 정의할 수 있습니다.

GitLab Runner는 GitLab CI/CD와 함께 작동하여 파이프라인에서 작업을 실행하는 애플리케이션입니다.

개발자가 GitLab에 코드를 푸시하면 .gitlab-ci.yml 파일에 자동화된 작업을 정의할 수 있습니다. 이러한 작업에는 테스트 실행, 애플리케이션 빌드, 코드 배포 등이 포함될 수 있습니다. GitLab Runner는 컴퓨팅 인프라에서 이러한 작업을 실행하는 애플리케이션입니다.

관리자로서 CI/CD 작업이 실행되는 인프라를 제공하고 관리할 책임이 있습니다. 여기에는 GitLab Runner 애플리케이션 설치, 구성, 그리고 조직의 CI/CD 워크로드를 처리할 충분한 용량 확보가 포함됩니다.

GitLab Runner가 하는 일#

GitLab Runner는 GitLab 인스턴스에 연결하여 CI/CD 작업을 기다립니다. 파이프라인이 실행되면 GitLab은 사용 가능한 러너에게 작업을 전송합니다. 러너는 작업을 실행하고 결과를 GitLab에 보고합니다.

GitLab Runner에는 다음과 같은 기능이 있습니다.

여러 작업을 동시에 실행합니다.
여러 서버(프로젝트별 포함)에서 여러 토큰을 사용합니다.
토큰별 동시 작업 수를 제한합니다.
작업 실행 방식:
- 로컬에서 실행.
- Docker 컨테이너 사용.
- Docker 컨테이너와 SSH를 통한 작업 실행.
- 다양한 클라우드 및 가상화 하이퍼바이저에서 자동 스케일링으로 Docker 컨테이너 사용.
- 원격 SSH 서버에 연결.
Go로 작성되어 추가 요구 사항 없이 단일 바이너리로 배포됩니다.
Bash, PowerShell Core, Windows PowerShell을 지원합니다.
GNU/Linux, macOS, Windows에서 동작합니다(Docker를 실행할 수 있는 거의 모든 환경).
작업 실행 환경의 커스터마이징을 허용합니다.
재시작 없이 자동 설정 리로드.
Docker, Docker-SSH, Parallels 또는 SSH 실행 환경 지원으로 원활한 설정.
Docker 컨테이너 캐싱 활성화.
GNU/Linux, macOS, Windows 서비스로 원활한 설치.
내장 Prometheus 메트릭 HTTP 서버.
Prometheus 메트릭 및 기타 작업별 데이터를 모니터링하고 GitLab으로 전달하는 레퍼리 워커.

러너 실행 흐름#

이 다이어그램은 러너가 등록되는 방법과 작업이 요청되고 처리되는 방법을 보여줍니다. 또한 등록 및 인증 토큰과 작업 토큰을 사용하는 작업도 보여줍니다.

Mermaid 다이어그램 (19줄)

소스 코드 보기

sequenceDiagram
    participant GitLab
    participant GitLabRunner
    participant Executor
opt registration
  GitLabRunner -&gt;&gt;+ GitLab: POST /api/v4/runners with registration_token
  GitLab --&gt;&gt;- GitLabRunner: Registered with runner_token
end

loop job requesting and handling
  GitLabRunner -&gt;&gt;+ GitLab: POST /api/v4/jobs/request with runner_token
  GitLab --&gt;&gt;+ GitLabRunner: job payload with job_token
  GitLabRunner -&gt;&gt;+ Executor: Job payload
  Executor -&gt;&gt;+ GitLab: clone sources with job_token
  Executor -&gt;&gt;+ GitLab: download artifacts with job_token
  Executor --&gt;&gt;- GitLabRunner: return job output and status
  GitLabRunner --&gt;&gt;- GitLab: updating job output and status with job_token
end</code></pre></details></div>

러너 배포 옵션#
GitLab 호스팅 러너#
GitLab 호스팅 러너는 GitLab이 관리하며 GitLab.com에서 사용할 수 있습니다.
이러한 러너는 설치하거나 유지 관리할 필요가 없으며, GitLab이 서비스로 제공합니다.
그러나 실행 환경에 대한 제어가 제한되어 있으며 인프라를 커스터마이징할 수 없습니다.
Self-managed 러너#
Self-managed 러너는 자체 인프라에 직접 설치, 구성, 관리하는 GitLab Runner 인스턴스입니다. 모든 GitLab 설치에서 self-managed 러너를 설치하고 등록할 수 있습니다.
관리자는 일반적으로 self-managed 러너를 사용합니다.
GitLab이 호스팅하고 관리하는 GitLab 호스팅 러너와 달리, self-managed 러너는 완전한 제어권을 가집니다.
GitLab Runner 버전#
호환성을 위해 GitLab Runner의 major.minor 버전은
GitLab의 major 및 minor 버전과 동기화되어야 합니다. 구버전 러너가 최신 GitLab 버전에서 작동할 수 있고, 그 반대도 마찬가지입니다. 그러나 버전 차이가 있으면 기능이 제공되지 않거나 제대로 작동하지 않을 수 있습니다.
minor 버전 업데이트 간에는 하위 호환성이 보장됩니다. 그러나 때로는 GitLab의 minor 버전 업데이트가 GitLab Runner가 동일한 minor 버전이어야 하는 새로운 기능을 도입할 수 있습니다.
자체 러너를 호스팅하지만 리포지터리는 GitLab.com에서 호스팅하는 경우,
GitLab.com은 지속적으로 업데이트되므로
GitLab Runner를 최신 버전으로 업데이트하세요.
트러블슈팅#
일반적인 이슈를 트러블슈팅하는 방법을 알아보세요.
용어집#

GitLab Runner: 대상 컴퓨팅 플랫폼에서 GitLab 파이프라인의 CI/CD 작업을 실행하는 애플리케이션.
러너: 작업을 실행할 수 있는 GitLab Runner의 구성된 인스턴스. 실행기 유형에 따라 이 머신은 러너 매니저의 로컬(shell 또는 docker 실행기)이거나 오토스케일러(docker-autoscaler 또는 kubernetes)가 생성한 원격 머신일 수 있습니다.
러너 구성: UI에 러너로 표시되는 config.toml의 단일 [[runner]] 항목.
러너 매니저: config.toml 파일을 읽고 모든 러너 구성 및 작업 실행을 동시에 실행하는 프로세스.
머신: 러너가 동작하는 가상 머신(VM) 또는 파드. GitLab Runner는 고유하고 영구적인 머신 ID를 자동으로 생성하여 여러 머신이 동일한 러너 구성을 받을 때 작업이 별도로 라우팅될 수 있지만 러너 구성은 UI에서 그룹화됩니다.
실행기: GitLab Runner가 작업을 실행하는 데 사용하는 방법(Docker, Shell, Kubernetes 등).
파이프라인: 코드가 GitLab에 푸시될 때 자동으로 실행되는 작업의 컬렉션.
작업: 테스트 실행 또는 애플리케이션 빌드와 같은 파이프라인의 단일 태스크.
러너 토큰: 러너가 GitLab으로 인증할 수 있는 고유 식별자.
태그: 러너에 할당되어 실행할 수 있는 작업을 결정하는 레이블.
동시 작업: 러너가 동시에 실행할 수 있는 작업 수.
Self-managed 러너: 자체 인프라에 설치하고 관리하는 러너.
GitLab 호스팅 러너: GitLab이 제공하고 관리하는 러너.

자세한 내용은 공식 GitLab 단어 목록과 GitLab Runner에 대한 GitLab 아키텍처 항목을 참조하세요.
기여#
기여를 환영합니다. 자세한 내용은 CONTRIBUTING.md와 개발 문서를 참조하세요.
GitLab Runner 프로젝트의 리뷰어라면 잠시 시간을 내어 GitLab Runner 리뷰하기 문서를 읽어보세요.
GitLab Runner 프로젝트의 릴리스 프로세스도 검토할 수 있습니다.
변경 로그#
최근 변경 사항을 보려면 CHANGELOG를 참조하세요.
라이선스#
이 코드는 MIT 라이선스에 따라 배포됩니다. LICENSE 파일을 확인하세요.


Docs/GitLab/Runner
GitLab Runner
Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기
번역일: 2026-05-22
요약
GitLab Runner는 GitLab CI/CD와 함께 작동하여 파이프라인에서 작업을 실행하는 애플리케이션입니다. 개발자가 GitLab에 코드를 푸시하면 .gitlab-ci.yml 파일에 자동화된 작업을 정의할 수 있습니다.
GitLab Runner는 GitLab CI/CD와 함께 작동하여 파이프라인에서 작업을 실행하는 애플리케이션입니다.
개발자가 GitLab에 코드를 푸시하면 .gitlab-ci.yml 파일에 자동화된 작업을 정의할 수 있습니다.
이러한 작업에는 테스트 실행, 애플리케이션 빌드, 코드 배포 등이 포함될 수 있습니다.
GitLab Runner는 컴퓨팅 인프라에서 이러한 작업을 실행하는 애플리케이션입니다.
관리자로서 CI/CD 작업이 실행되는 인프라를 제공하고 관리할 책임이 있습니다.
여기에는 GitLab Runner 애플리케이션 설치, 구성, 그리고 조직의 CI/CD 워크로드를 처리할 충분한 용량 확보가 포함됩니다.
GitLab Runner가 하는 일#
GitLab Runner는 GitLab 인스턴스에 연결하여 CI/CD 작업을 기다립니다. 파이프라인이 실행되면 GitLab은 사용 가능한 러너에게 작업을 전송합니다.
러너는 작업을 실행하고 결과를 GitLab에 보고합니다.
GitLab Runner에는 다음과 같은 기능이 있습니다.

여러 작업을 동시에 실행합니다.
여러 서버(프로젝트별 포함)에서 여러 토큰을 사용합니다.
토큰별 동시 작업 수를 제한합니다.
작업 실행 방식:

로컬에서 실행.
Docker 컨테이너 사용.
Docker 컨테이너와 SSH를 통한 작업 실행.
다양한 클라우드 및 가상화 하이퍼바이저에서 자동 스케일링으로 Docker 컨테이너 사용.
원격 SSH 서버에 연결.


Go로 작성되어 추가 요구 사항 없이 단일 바이너리로 배포됩니다.
Bash, PowerShell Core, Windows PowerShell을 지원합니다.
GNU/Linux, macOS, Windows에서 동작합니다(Docker를 실행할 수 있는 거의 모든 환경).
작업 실행 환경의 커스터마이징을 허용합니다.
재시작 없이 자동 설정 리로드.
Docker, Docker-SSH, Parallels 또는 SSH 실행 환경 지원으로 원활한 설정.
Docker 컨테이너 캐싱 활성화.
GNU/Linux, macOS, Windows 서비스로 원활한 설치.
내장 Prometheus 메트릭 HTTP 서버.
Prometheus 메트릭 및 기타 작업별 데이터를 모니터링하고 GitLab으로 전달하는 레퍼리 워커.

러너 실행 흐름#
이 다이어그램은 러너가 등록되는 방법과 작업이 요청되고 처리되는 방법을 보여줍니다. 또한 등록 및 인증 토큰과 작업 토큰을 사용하는 작업도 보여줍니다.
Mermaid 다이어그램 (19줄)
소스 코드 보기
sequenceDiagram
    participant GitLab
    participant GitLabRunner
    participant Executor
opt registration
  GitLabRunner -&gt;&gt;+ GitLab: POST /api/v4/runners with registration_token
  GitLab --&gt;&gt;- GitLabRunner: Registered with runner_token
end

loop job requesting and handling
  GitLabRunner -&gt;&gt;+ GitLab: POST /api/v4/jobs/request with runner_token
  GitLab --&gt;&gt;+ GitLabRunner: job payload with job_token
  GitLabRunner -&gt;&gt;+ Executor: Job payload
  Executor -&gt;&gt;+ GitLab: clone sources with job_token
  Executor -&gt;&gt;+ GitLab: download artifacts with job_token
  Executor --&gt;&gt;- GitLabRunner: return job output and status
  GitLabRunner --&gt;&gt;- GitLab: updating job output and status with job_token
end</code></pre></details></div>

러너 배포 옵션#
GitLab 호스팅 러너#
GitLab 호스팅 러너는 GitLab이 관리하며 GitLab.com에서 사용할 수 있습니다.
이러한 러너는 설치하거나 유지 관리할 필요가 없으며, GitLab이 서비스로 제공합니다.
그러나 실행 환경에 대한 제어가 제한되어 있으며 인프라를 커스터마이징할 수 없습니다.
Self-managed 러너#
Self-managed 러너는 자체 인프라에 직접 설치, 구성, 관리하는 GitLab Runner 인스턴스입니다. 모든 GitLab 설치에서 self-managed 러너를 설치하고 등록할 수 있습니다.
관리자는 일반적으로 self-managed 러너를 사용합니다.
GitLab이 호스팅하고 관리하는 GitLab 호스팅 러너와 달리, self-managed 러너는 완전한 제어권을 가집니다.
GitLab Runner 버전#
호환성을 위해 GitLab Runner의 major.minor 버전은
GitLab의 major 및 minor 버전과 동기화되어야 합니다. 구버전 러너가 최신 GitLab 버전에서 작동할 수 있고, 그 반대도 마찬가지입니다. 그러나 버전 차이가 있으면 기능이 제공되지 않거나 제대로 작동하지 않을 수 있습니다.
minor 버전 업데이트 간에는 하위 호환성이 보장됩니다. 그러나 때로는 GitLab의 minor 버전 업데이트가 GitLab Runner가 동일한 minor 버전이어야 하는 새로운 기능을 도입할 수 있습니다.
자체 러너를 호스팅하지만 리포지터리는 GitLab.com에서 호스팅하는 경우,
GitLab.com은 지속적으로 업데이트되므로
GitLab Runner를 최신 버전으로 업데이트하세요.
트러블슈팅#
일반적인 이슈를 트러블슈팅하는 방법을 알아보세요.
용어집#

GitLab Runner: 대상 컴퓨팅 플랫폼에서 GitLab 파이프라인의 CI/CD 작업을 실행하는 애플리케이션.
러너: 작업을 실행할 수 있는 GitLab Runner의 구성된 인스턴스. 실행기 유형에 따라 이 머신은 러너 매니저의 로컬(shell 또는 docker 실행기)이거나 오토스케일러(docker-autoscaler 또는 kubernetes)가 생성한 원격 머신일 수 있습니다.
러너 구성: UI에 러너로 표시되는 config.toml의 단일 [[runner]] 항목.
러너 매니저: config.toml 파일을 읽고 모든 러너 구성 및 작업 실행을 동시에 실행하는 프로세스.
머신: 러너가 동작하는 가상 머신(VM) 또는 파드. GitLab Runner는 고유하고 영구적인 머신 ID를 자동으로 생성하여 여러 머신이 동일한 러너 구성을 받을 때 작업이 별도로 라우팅될 수 있지만 러너 구성은 UI에서 그룹화됩니다.
실행기: GitLab Runner가 작업을 실행하는 데 사용하는 방법(Docker, Shell, Kubernetes 등).
파이프라인: 코드가 GitLab에 푸시될 때 자동으로 실행되는 작업의 컬렉션.
작업: 테스트 실행 또는 애플리케이션 빌드와 같은 파이프라인의 단일 태스크.
러너 토큰: 러너가 GitLab으로 인증할 수 있는 고유 식별자.
태그: 러너에 할당되어 실행할 수 있는 작업을 결정하는 레이블.
동시 작업: 러너가 동시에 실행할 수 있는 작업 수.
Self-managed 러너: 자체 인프라에 설치하고 관리하는 러너.
GitLab 호스팅 러너: GitLab이 제공하고 관리하는 러너.

자세한 내용은 공식 GitLab 단어 목록과 GitLab Runner에 대한 GitLab 아키텍처 항목을 참조하세요.
기여#
기여를 환영합니다. 자세한 내용은 CONTRIBUTING.md와 개발 문서를 참조하세요.
GitLab Runner 프로젝트의 리뷰어라면 잠시 시간을 내어 GitLab Runner 리뷰하기 문서를 읽어보세요.
GitLab Runner 프로젝트의 릴리스 프로세스도 검토할 수 있습니다.
변경 로그#
최근 변경 사항을 보려면 CHANGELOG를 참조하세요.
라이선스#
이 코드는 MIT 라이선스에 따라 배포됩니다. LICENSE 파일을 확인하세요.
목차
GitLab Runner가 하는 일러너 실행 흐름러너 배포 옵션GitLab 호스팅 러너Self-managed 러너GitLab Runner 버전트러블슈팅용어집기여변경 로그라이선스