GitLab Runner

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

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

GitLab 호스팅 러너 사용하기

GitLab.com 또는 GitLab Dedicated를 사용하는 경우 GitLab 호스팅 러너에서 CI/CD 작업을 실행할 수 있습니다.
이 러너는 GitLab에서 관리되며 GitLab.com과 완전히 통합되어 있습니다.
기본적으로 이러한 러너는 모든 프로젝트에 대해 활성화되어 있습니다.
프로젝트에 대한 소유자 역할이 있는 경우 러너를 비활성화할 수 있습니다.

자체 관리 러너 사용하기

Tier: Free, Premium, Ultimate Offering: Self-managed

또는 GitLab Runner를 설치하고 GitLab.com 또는 자체 인스턴스에서 자신의 러너를 등록할 수 있습니다.
자체 관리 러너를 사용하려면, 소유하거나 관리하는 인프라에 GitLab Runner를 설치해야 합니다.

러너 모음의 규모 조정하기

조직의 러너 수가 증가하면,
이 러너의 성능을 모니터링하고 조정하기 위한 계획을 세워야 합니다.

GitLab Runner 버전

호환성상의 이유로, GitLab Runner의 major.minor 버전은 GitLab의 major 및 minor 버전과 동기화되어 있어야 합니다.
구형 러너는 최신 GitLab 버전과 여전히 작동할 수 있으며, 그 반대도 마찬가지입니다.
그러나 버전 차이가 있을 경우, 기능이 제대로 작동하지 않거나 사용 불가능할 수 있습니다.

마이너 버전 업데이트 간에는 하위 호환성이 보장됩니다.
그러나 가끔씩 GitLab의 마이너 버전 업데이트로 인해 GitLab Runner가 동일한 마이너 버전이어야 하는 새로운 기능이 도입될 수 있습니다.

note
GitLab Runner 15.0은 변경 사항을 도입했습니다
등록 API 요청 형식이 변경되었습니다. 이는 GitLab Runner가 14.8 이하 버전의 GitLab과 통신하지 못하게 합니다.
GitLab 버전에 적합한 러너 버전을 사용하거나 GitLab 애플리케이션을 업그레이드해야 합니다.

자체 러너를 호스팅하지만 리포지토리를 GitLab.com에 호스팅하는 경우,
GitLab Runner를 최신 버전으로 업데이트하는 것이 중요합니다.
GitLab.com은 지속적으로 업데이트됩니다.

러너 등록

애플리케이션을 설치한 후, 등록
개별 러너를 등록합니다. 러너는 GitLab에서 오는 CI/CD 작업을 실행하는 에이전트입니다.

러너를 등록할 때, GitLab 인스턴스와 GitLab Runner가 설치된 머신 간의 통신을 설정하는 것입니다.

러너는 일반적으로 GitLab Runner를 설치한 동일한 머신에서 작업을 처리합니다.
그러나 러너가 컨테이너, Kubernetes 클러스터 또는 클라우드의 자동 스케일 인스턴스에서 작업을 처리하도록 할 수도 있습니다.

실행기

러너를 등록할 때, 실행기를 선택해야 합니다.

실행기는 각 작업이 실행되는 환경을 결정합니다.

예를 들어:

  • CI/CD 작업에서 PowerShell 명령을 실행하려는 경우, Windows 서버에 GitLab Runner를 설치한 다음 셸 실행기를 사용하는 러너를 등록할 수 있습니다.
  • CI/CD 작업에서 커스텀 Docker 컨테이너에서 명령을 실행하려는 경우, Linux 서버에 GitLab Runner를 설치하고 Docker 실행기를 사용하는 러너를 등록할 수 있습니다.

이들은 가능한 구성 중 일부에 불과합니다.
가상 머신에 GitLab Runner를 설치하고 다른 가상 머신을 실행기로 사용할 수 있습니다.

Docker 컨테이너에 GitLab Runner를 설치하고 작업을 실행하기 위해 Docker 실행기를 선택하면,
때때로 “Docker-in-Docker” 구성이라고도 합니다.

GitLab UI에서 러너에 대한 접근 권한

러너를 등록하기 전에, GitLab의 모든 사용자가 접근할 수 있도록 할 것인지, 아니면 특정 GitLab 그룹이나 프로젝트로 제한할 것인지를 결정해야 합니다.

접근할 수 있는 러너의 유형은 다음과 같이 세 가지입니다:

러너의 범위는 등록하는 동안 정의됩니다.
이것은 러너가 어떤 프로젝트에서 사용 가능한지 아는 방법입니다.

태그

러너를 등록할 때 태그를 추가할 수 있습니다.

CI/CD 작업이 실행될 때, 할당된 태그를 보고 어떤 러너를 사용할지 알 수 있습니다.
태그는 작업에 사용할 수 있는 러너 목록을 필터링하는 유일한 방법입니다.

예를 들어, 러너에 ruby 태그가 있는 경우, 다음 코드를 프로젝트의 .gitlab-ci.yml 파일에 추가합니다:

job:
  tags:
    - ruby

작업이 실행될 때, ruby 태그가 있는 러너를 사용합니다.

러너 구성

러너를 구성하려면 config.toml 파일을 편집할 수 있습니다.
이 파일은 러너 설치 과정에서 설치되는 파일입니다.

이 파일에서는 특정 러너 또는 모든 러너에 대한 설정을 편집할 수 있습니다.

로깅 및 캐시와 같은 설정을 지정할 수 있습니다.
동시성, 메모리, CPU 제한 등을 설정할 수 있습니다.

러너 모니터링

Prometheus를 사용하여 모니터링할 수 있습니다.
현재 실행 중인 작업의 수 및 러너가 사용하는 CPU 양과 같은 정보를 볼 수 있습니다.

러너를 사용하여 작업 실행

러너가 구성되고 프로젝트에서 사용할 수 있게 되면,
CI/CD 작업에서 러너를 사용할 수 있습니다.

기능

GitLab 러너는 다음과 같은 기능을 가지고 있습니다.

  • 여러 작업을 동시에 실행합니다.
  • 여러 서버와 함께 여러 토큰을 사용할 수 있습니다(프로젝트별로도 가능).
  • 토큰당 동시 작업 수를 제한할 수 있습니다.
  • 작업은 다음을 통해 실행될 수 있습니다:
    • 로컬에서.
    • 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에 전송하는 심판 작업자.

실행 흐름

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

sequenceDiagram participant GitLab participant GitLabRunner participant Executor opt registration GitLabRunner ->>+ GitLab: POST /api/v4/runners with registration_token GitLab -->>- GitLabRunner: Registered with runner_token end loop 작업 요청 및 처리 GitLabRunner ->>+ GitLab: POST /api/v4/jobs/request with runner_token GitLab -->>+ GitLabRunner: job payload with job_token GitLabRunner ->>+ Executor: Job payload Executor ->>+ GitLab: clone sources with job_token Executor ->>+ GitLab: download artifacts with job_token Executor -->>- GitLabRunner: return job output and status GitLabRunner -->>- GitLab: updating job output and status with job_token end

용어집

이 용어집은 GitLab Runner와 관련된 용어의 정의를 제공합니다.

  • GitLab Runner: GitLab CI 작업을 대상 컴퓨팅 플랫폼에서 실행하기 위해 설치하는 애플리케이션입니다.

  • 러너 구성: UI에 러너로 표시되는 config.toml의 단일 [[runner]] 항목입니다.

  • 러너 관리자: config.toml을 읽고 모든 러너 구성을 동시에 실행하는 프로세스입니다.

  • 러너: 선택된 머신에서 작업을 실행하는 프로세스입니다. 실행기의 종류에 따라 이 머신은 러너 관리자에 로컬(shell 또는 docker 실행기)일 수도 있고, 자동 스케일러에 의해 만들어진 원격 머신일 수도 있습니다(docker-autoscaler 또는 kubernetes).

  • 머신: 러너가 작동하는 가상 머신(VM) 또는 포드입니다. GitLab Runner는 고유하고 지속 가능한 머신 ID를 자동으로 생성하므로 여러 머신이 동일한 러너 구성을 가진 경우, 작업을 별도로 라우팅할 수 있지만 UI에서 러너 구성은 그룹화됩니다.

또한 공식 GitLab 용어집과 GitLab 아키텍처 항목의 GitLab Runner를 참조하세요.

문제 해결

일반적인 문제를 문제 해결하는 방법을 알아보세요.

기여

기여는 환영합니다. CONTRIBUTING.md 및 개발 문서에서 자세한 내용을 확인하세요.

GitLab Runner 프로젝트의 리뷰어라면 잠시 시간을 내어 GitLab Runner 리뷰 문서를 읽어보세요.

GitLab Runner 프로젝트의 릴리스 프로세스도 검토할 수 있습니다.

변경 로그

CHANGELOG를 참고하여 최근 변경 사항을 확인하세요.

라이센스

이 코드는 MIT 라이센스에 따라 배포됩니다. LICENSE 파일을 확인하세요.