GitLab Runner

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

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

GitLab.com SaaS 러너 사용

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

Self-managed 러너 사용

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

또는 GitLab Runner를 설치하고 GitLab.com 또는 자체 인스턴스에 자체 러너를 등록할 수 있습니다. Self-managed 러너를 사용하려면 고유의 러너를 설치하여 소유하거나 관리하는 인프라에 GitLab Runner를 등록하세요.

러너 편대 확장

조직이 러너 편대로 확장될 때 이러한 러너의 성능을 모니터링하고 조정하는 방법을 계획해야 합니다.

GitLab Runner 버전

호환성을 유지하기 위해 GitLab Runner의 메이저.마이너 버전은 GitLab의 메이저 및 마이너 버전과 동기화되어야 합니다. 이전 러너는 최신 GitLab 버전과 호환될 수 있으며 그 반대도 마찬가지입니다. 그러나 버전 차이가 있는 경우 기능이 제대로 작동하지 않을 수 있습니다.

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

참고: GitLab Runner 15.0은 등록 API 요청 형식을 변경했습니다. 이로 인해 GitLab Runner가 14.8보다 낮은 GitLab 버전과 통신하지 못하게 됩니다. GitLab 버전에 적합한 Runner 버전을 사용하거나 GitLab 애플리케이션을 업그레이드해야 합니다.

자체 러너를 호스팅하지만 저장소를 GitLab.com에 호스팅하는 경우 GitLab Runner를 최신 버전으로 업데이트하세요. GitLab.com은 지속적으로 업데이트됩니다.

러너 등록

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

러너를 등록하면 GitLab 인스턴스와 GitLab Runner가 설치된 기기 사이의 통신을 설정합니다.

보통 러너는 GitLab Runner를 설치한 기기에서 작업을 처리합니다. 그러나 러너를 컨테이너에서 작업하거나 쿠버네티스 클러스터 또는 클라우드의 자동 크기 조정 인스턴스에서 작업하도록 할 수도 있습니다.

Executors

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

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

예를 들어: - CI/CD 작업을 PowerShell 명령으로 실행하려면 Windows 서버에 GitLab Runner를 설치한 다음 셸 실행기를 사용하는 러너를 등록할 수 있습니다. - CI/CD 작업을 사용자 정의 Docker 컨테이너에서 실행하려면 Linux 서버에 GitLab Runner를 설치한 다음 Docker 실행기를 사용하는 러너를 등록할 수 있습니다.

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

Docker 컨테이너에 GitLab Runner를 설치하고 작업을 실행하기 위해 도커 실행기를 선택하는 경우 “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 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에 전달하기 위한 Referee workers를 모니터링하고 전달합니다.

러너 실행 흐름

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

sequenceDiagram participant GitLab participant GitLabRunner participant Executor opt 등록 GitLabRunner ->>+ GitLab: 등록 토큰으로 POST /api/v4/runners GitLab -->>- GitLabRunner: 러너 토큰으로 등록됨 end loop 작업 요청 및 처리 GitLabRunner ->>+ GitLab: 러너 토큰으로 POST /api/v4/jobs/request GitLab -->>+ GitLabRunner: 작업 토큰이 포함된 작업 페이로드 GitLabRunner ->>+ Executor: 작업 페이로드 Executor ->>+ GitLab: 작업 토큰으로 소스 복제 Executor ->>+ GitLab: 작업 토큰으로 아티팩트 다운로드 Executor -->>- GitLabRunner: 작업 결과 및 상태 반환 GitLabRunner -->>- GitLab: 작업 결과 및 상태 업데이트(작업 토큰 사용) end

용어집

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

  • GitLab Runner: 대상 컴퓨팅 플랫폼에서 GitLab CI 작업을 실행하는 애플리케이션.
  • 런너 구성: UI에서 러너로 표시되는 config.toml의 단일 [[runner]] 항목.
  • 러너 매니저: config.toml을 읽고 모든 러너 구성을 동시에 실행하는 프로세스.
  • 런너: 선택된 머신에서 작업을 실행하는 프로세스. Executor 유형에 따라 이 머신은 러너 매니저에 로컬일 수도 있음(shell 또는 docker Executor) 또는 오토스케일러가 생성한 원격 머신일 수도 있음(docker-autoscaler 또는 kubernetes).
  • 머신: 러너가 작동하는 가상 머신(VM) 또는 팟. GitLab Runner는 여러 머신에 동일한 러너 구성이 제공되었을 때 작업을 별도로 라우팅할 수 있도록 고유하고 지속적인 머신 ID를 자동으로 생성하므로 UI에서는 러너 구성이 그룹화됩니다.

공식 GitLab 용어집 및 GitLab Runner의 GitLab 아키텍처 항목도 참조하세요.

문제 해결

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

기여

기여를 환영합니다. 자세한 내용은 CONTRIBUTING.md 및 개발 문서를 참조하세요.

만약 GitLab Runner 프로젝트의 리뷰어이신 경우, GitLab Runner 리뷰 방법 문서를 잠시 읽어보세요.

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

변경 로그

최근 변경 사항을 보려면 CHANGELOG를 참조하세요.

라이선스

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