GitLab Runner 개발에 기여하기
GitLab Runner는 두 가지 모드로 작동할 수 있는 Go 바이너리입니다: instance 실행기 모드(1)로 GitLab Runner를 개발하는 경우, 필요한 설정은 Go 환경뿐입니다. 다음 지침은 mise를 사용하여 Go 버전을 관리하는 Go 환경을 설정합니다.
GitLab Runner는 두 가지 모드로 작동할 수 있는 Go 바이너리입니다:
- GitLab Runner가 로컬에서 작업을 실행하는 방식("instance" 실행기).
- 러너 매니저가 GitLab Runner Helper를 사용하여 아티팩트를 가져오는 오토스케일 환경에 작업을 위임하는 방식.
instance 실행기 모드(1)로 GitLab Runner를 개발하는 경우, 필요한 설정은 Go 환경뿐입니다. 매니저 및 Helper 모드(2)로 GitLab Runner를 개발하는 경우, Docker 빌드 환경도 필요합니다. 또한 Kubernetes에서 매니저 또는 Helper를 실행하려면 작동하는 클러스터가 필요합니다.
다음 지침은 mise를 사용하여 Go 버전을 관리하는 Go 환경을 설정합니다. 이미 이 설정이 있거나 스스로 알고 있는 경우 2단계("의존성 및 Go 런타임 설치")를 건너뛸 수 있습니다.
로컬에서 Docker 및 Kubernetes를 제공하기 위해 3단계에서 Rancher Desktop을 설정합니다. 하나 또는 둘 다 필요하지 않으면 3단계("Rancher Desktop 설치")를 건너뛰거나 Rancher Desktop에서 k3s(Kubernetes)를 비활성화할 수 있습니다.
권장 환경#
Go와 Rancher Desktop을 개발용으로 설치하기 위한 권장 환경은 로컬 노트북 또는 데스크탑입니다. 클라우드에서 Rancher Desktop을 실행하기 위해 중첩 가상화를 사용하는 것도 가능하지만(k3s를 VM에서 실행) 설정이 더 복잡합니다.
러너 Shorts 비디오 튜토리얼#
설정 및 변경에 대한 Runner Shorts(약 20분 비디오)를 따라가도 됩니다:
- 시작하기 전에 위의 권장 환경 섹션을 읽어보세요
- GitLab Runner 개발 환경 설정
- GitLab Runner 코드 워크스루
- GitLab Runner 변경 사항 로컬에서 만들고 테스트하기
1. GitLab Runner 클론#
git clone https://gitlab.com/gitlab-org/gitlab-runner.git
오토스케일 모드(매니저 및 Helper)에서 GitLab Runner를 개발하는 경우 Taskscaler, Fleeting 및 관련 플러그인 중 하나 이상을 체크아웃할 수 있습니다. 한 패키지의 로컬 변경 사항이 다른 패키지에 표시되도록 Go 워크스페이스를 사용하세요.
git clone https://gitlab.com/gitlab-org/fleeting/taskscaler.git
git clone https://gitlab.com/gitlab-org/fleeting/fleeting.git
git clone https://gitlab.com/gitlab-org/fleeting/fleeting-plugin-aws.git
git clone https://gitlab.com/gitlab-org/fleeting/fleeting-plugin-googlecompute.git
go work init
go work use gitlab-runner
go work use taskscaler
go work use fleeting
go work use fleeting-plugin-aws
go work use fleeting-plugin-googlecompute
2. 의존성 및 Go 런타임 설치#
GitLab Runner 프로젝트는 의존성을 관리하기 위해 mise를 사용합니다.
개발 환경을 설정하는 가장 간단한 방법은 mise를 사용하는 것입니다.
cd gitlab-runner
mise install
sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.26.1.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
sudo yum install mercurial wget make
sudo yum groupinstall 'Development Tools'
wget https://storage.googleapis.com/golang/go1.26.1.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
바이너리 패키지 사용:
wget https://storage.googleapis.com/golang/go1.26.1.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
설치 패키지 사용:
wget https://storage.googleapis.com/golang/go1.26.1.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
pkg install go-1.26.1 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
3. Rancher Desktop 설치#
Docker 실행기를 사용할 때 GitLab Runner에 내장되어 로드되는 사전 빌드된 이미지를 만들기 위해 Docker 엔진이 필요합니다. 로컬 Kubernetes 클러스터는 Kubernetes 실행기 개발에 도움이 됩니다. Rancher Desktop은 두 가지를 모두 제공합니다.
Rancher Desktop을 설치하려면 OS에 맞는 설치 지침을 따르세요.
Rancher Desktop을
dockerd (moby)를 사용하도록 구성하고Administrative Access를 활성화해야 합니다.
4. GitLab Runner 의존성 설치#
make deps
mise reshim
FreeBSD에서는 gmake deps를 사용하세요
5. GitLab Runner 빌드#
Go 툴체인을 사용하여 GitLab Runner를 컴파일하세요:
make runner-and-helper-bin-host
make runner-and-helper-bin-host는 make runner-bin-host의 상위 집합으로, Runner Helper Docker 아카이브 의존성 빌드도 처리합니다.
6. GitLab Runner 실행#
./out/binaries/gitlab-runner run
일반적인 명령줄 인수(--debug 포함)를 사용할 수 있습니다:
./out/binaries/gitlab-runner --debug run
Docker 이미지 빌드#
Docker 이미지를 빌드하려면 make runner-and-helper-docker-host를 실행하세요:
gitlab-runner-helper를 빌드하고 이를 기반으로 Helper Docker 이미지를 만듭니다.linux/amd64용 GitLab Runner를 컴파일합니다.- 러너용 DEB 패키지를 빌드합니다. 공식 GitLab Runner 이미지는 Alpine과 Ubuntu 기반이며, Ubuntu 이미지 빌드는 DEB 패키지를 사용합니다.
gitlab/gitlab-runner이미지의 Alpine 및 Ubuntu 버전을 빌드합니다.
GitLab Runner의 새 오토스케일링(Taskscaler) (15.6.0 이후)#
차세대 러너 오토스케일링 아키텍처는 모든 환경에서 작동하는 새로운 오토스케일링 메커니즘을 추가합니다. 이는 현재의 모든 오토스케일링 메커니즘(예: Docker Machine)을 대체할 것입니다. 이 새로운 메커니즘은 프리 알파 상태이며 활발히 개발 중입니다. GitLab Runner에서 사용되는 두 가지 새로운 라이브러리가 있습니다:
HEAD의 GitLab Runner를 사용하기 위해 이 라이브러리를 체크아웃할 필요는 없지만, 오토스케일링 공간에서의 일부 개발은 그곳에서 이루어질 수 있습니다. 또한 Taskscaler와 Fleeting 외에도 GitLab Runner를 특정 클라우드 공급자(예: Google Computer 또는 AWS EC2)에 적응시키는 여러 Fleeting 플러그인이 있습니다. 위의 작성된 지침("GitLab Runner 클론")은 코드를 체크아웃하는 방법을 보여주며 비디오("Runner Shorts")는 이를 사용하는 방법을 보여줍니다. 이 지침은 플러그인과 함께 GitLab Runner를 사용하는 방법을 보여줍니다.
각 플러그인에는 바이너리를 빌드하고 기본 인스턴스 그룹을 구성하는 방법에 대한 지침이 포함됩니다. 이 작업은 이 이슈에서 진행 중입니다. 표준 빌드 및 구성 지침은 각 플러그인과 함께 제공되지만, 그 전까지는 여기에 일반 지침이 있습니다.
플러그인 빌드#
플러그인으로 GitLab Runner를 실행하려면 실행 가능한 바이너리를 생성하여 시스템의 PATH에 배치하세요.
바이너리를 생성하려면 $GOPATH/bin이 PATH에 있는지 확인한 다음 go install을 사용하세요.
각 플러그인은 ./cmd/<plugin-name> 경로를 포함합니다. 예를 들어 fleeting-plugin-aws 디렉토리에서:
cd cmd/fleeting-plugin-aws/
go install
mise로 go 버전을 관리하는 경우 바이너리가 생성된 후 이 명령어를 실행하세요:
mise reshim
플러그인 사용#
GitLab Runner는 일반적인 방식으로 시작하지만 instance 실행기를 지정합니다. 또한 plugin_config 및 connector_config 아래에 인스턴스 그룹, 위치, 기본 인스턴스에 연결하는 방법에 대한 세부 정보를 지정합니다. GitLab Runner는 인스턴스 그룹을 찾고 초기 수의 유휴 VM을 만들어야 합니다. 구성된 인스턴스 러너가 작업을 선택하면 실행 중인 VM을 사용하고 fleeting-plugin-aws 플러그인에서 AWS 서비스 호출을 통해 교체합니다.
[[runners]]
name = "local-taskrunner"
url = "https://gitlab.com/"
token = "REDACTED"
executor = "instance"
shell = "bash"
[runners.autoscaler]
max_use_count = 1
max_instances = 20
plugin = "fleeting-plugin-aws" # 위에서 빌드한 Fleeting 플러그인 이름 [1].
[runners.autoscaler.plugin_config]
credentials_file = "/Users/josephburnett/.aws/credentials". # Auto Scaling Group(ASG)을 스케일링할 수 있는 자격 증명 [2].
name = "jburnett-taskrunner-asg" # ASG 이름.
project = "jburnett-ad8e5d54" # ASG 프로젝트.
region = "us-east-2" # ASG 리전.
[runners.autoscaler.connector_config]
username = "ubuntu" # 로그인을 위한 ASG 인스턴스 템플릿 사용자명.
[[runners.autoscaler.policy]]
idle_count = 5
idle_time = 0
scale_factor = 0.0
scale_factor_limit = 0
SIGTERM으로 GitLab Runner를 종료하면 이러한 프로세스 중 일부가 남아 있을 수 있습니다. 대신 SIGQUIT으로 종료하세요.
ASG는 오토스케일링이 비활성화되어야 합니다. GitLab Runner는 Taskscaler 라이브러리를 통해 오토스케일링을 처리합니다.
7. 로컬에서 테스트 스위트 실행#
GitLab Runner 테스트 스위트는 "코어" 테스트와 실행기 테스트로 구성됩니다. 실행기 테스트는 로컬 머신에 특정 바이너리가 설치되어 있어야 합니다. 이러한 바이너리 중 일부는 모든 운영 체제에 설치할 수 없습니다. 바이너리가 설치되지 않으면 해당 바이너리가 필요한 테스트는 건너뜁니다.
설치할 수 있는 바이너리:
- VirtualBox와 Vagrant; Vagrant Parallels 플러그인도 필요합니다
- minikube가 있는 kubectl
- Parallels Pro 또는 Business 에디션
- PowerShell
바이너리를 설치한 후 실행하세요:
make development_setup
테스트를 실행하려면:
make test
Kubernetes 통합 테스트#
일부 Kubernetes 통합 테스트는 실행하는 Kubernetes 클러스터의 특정 구성 또는 런타임 인수가 필요합니다. 클러스터 구성이 올바르지 않으면 이러한 테스트는 건너뜁니다. 개발자 워크스테이션에서 일반적으로 사용되는 Kubernetes 클러스터의 샘플 구성은 다음과 같습니다:
minikube
minikube delete
minikube config set container-runtime containerd
minikube config set feature-gates "ProcMountType=true"
minikube start
k3s
k3s server --tls-san=k3s --kube-apiserver-arg=feature-gates=ProcMountType=true
8. 선택한 Helper 이미지 버전으로 테스트 실행#
Helper 내부의 기능을 개발하는 경우 최신 변경 사항이 포함된 Docker 이미지 버전으로 테스트를 실행하는 것이 좋습니다.
-ldflags를 전달하지 않고 테스트를 실행하면 version.go의 기본 버전인 development가 사용됩니다. 이는 러너가 기본적으로 latest 태그가 있는 Helper 이미지를 가져오는 것을 의미합니다.
Make 타겟#
make 타겟은 -ldflags를 자동으로 주입합니다. 다음을 사용하여 모든 테스트를 실행할 수 있습니다:
make simple-test
make 타겟은 parallel_test_execute에도 -ldflags를 주입하며, CI/CD 작업에서 가장 일반적으로 사용됩니다.
커스텀 go test 인수#
더 커스터마이징된 go test 명령어가 필요한 경우 print_test_ldflags를 make 타겟으로 사용할 수 있습니다:
go test -ldflags "$(make print_test_ldflags)" -run TestDockerCommandBuildCancel -v ./executors/docker/...
GoLand에서#
현재 GoLand는 동적 Go 도구 인수를 지원하지 않으므로, make print_ldflags를 먼저 실행한 다음 설정에 붙여넣어야 합니다.
디버거를 사용하려면 마지막 두 플래그(-s -w)를 제거해야 합니다.
러너 및 Helper의 로컬 Docker 이미지#
다음 명령어를 사용하여 러너와 Helper를 로컬 Docker 이미지로 빌드할 수 있습니다:
make runner-local-image # gitlab-runner:local만 빌드
make helper-local-image # gitlab-runner-helper:local만 빌드
make runner-and-helper-local-image # 둘 다 빌드
빌드가 완료되면 이미지를 로컬에서 사용할 수 있습니다.
docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
gitlab-runner-helper local 1e0064619625 5 minutes ago 92.2MB
gitlab-runner local 1261a052d4ad 5 minutes ago 195MB
Kubernetes에서 Helper 이미지 사용#
로컬 Kubernetes 클러스터에서 로컬 이미지를 사용하려면 Docker 컨텍스트를 적절하게 설정해야 합니다. 예를 들어 minikube에서:
eval $(minikube docker-env)
make runner-and-helper-local-image
로컬 이미지 커스터마이징#
타겟은 완성도보다 편의성에 초점을 맞춥니다. 이러한 make 타겟으로 사용 가능한 모든 러너 및 Helper 구성을 만들 수 없습니다. 타겟은 Linux 이미지 생성만 지원합니다.
타겟 아키텍처는 기본적으로 호스트 머신 아키텍처입니다. 기본 러너 이미지 버전은 CI/CD 설정에 지정된 버전으로 기본 설정됩니다. 환경 변수를 설정하여 다양한 변형을 테스트할 수 있습니다. 가능한 값에 대한 지침은 기본 이미지 컨테이너 레지스트리에서 사용 가능한 기본 이미지를 확인하세요.
예시:
# ubuntu 기반 러너와 helper 만들기
LOCAL_FLAVOR=ubuntu make runner-and-helper-local-image
# 버전과 flavor 지정
RUNNER_IMAGES_VERSION=0.0.1 LOCAL_FLAVOR=ubuntu make runner-and-helper-local-image
# pwsh가 있는 ubuntu helper 이미지 만들기
# 참고: 이 flavor는 helper에만 지원되며 runner에는 지원되지 않습니다.
# amd64에서만 사용 가능합니다.
LOCAL_FLAVOR=ubuntu-pwsh LOCAL_ARCH=amd64 make helper-local-image
이러한 환경 변수는 유연성을 제공하지만, 타겟은 잘못된 설정으로부터 보호하지 않습니다. 운영 환경 시나리오에서는 CI/CD 파이프라인이 만드는 이미지를 사용하세요.
9. 선택적 도구 설치#
make lint타겟에 사용되는golangci-lint를 설치합니다.make lint-docs타겟에 사용되는markdown-lint와vale를 설치합니다.
도구가 없으면 Makefile 타겟을 실행할 때 설치 지침이 표시됩니다.
10. 기여하기#
gitlab-runner 코드 해킹을 시작할 수 있습니다. 코드를 편집하고 디버그하기 위한 IDE가 필요한 경우 사용할 수 있는 몇 가지 무료 제안이 있습니다:
- JetBrains GoLand IDE.
.vscode/extensions.json에 있는 워크스페이스 권장 확장 프로그램을 사용하는 Visual Studio Code.
빌드 의존성 관리#
GitLab Runner는 Go Modules를 사용하여 의존성을 관리합니다.
버전 태그를 사용할 수 있는 경우 업스트림 기본 브랜치의 의존성을 추가하지 마세요.
테스트#
러너 코드베이스는 다음과 같은 방식으로 단위 테스트와 통합 테스트를 구분합니다:
-
단위 테스트 파일은
_test.go접미사를 가지며 헤더에 다음 빌드 지시문을 포함합니다:// go:build !integration -
통합 테스트 파일은
_integration_test.go접미사를 가지며 헤더에 다음 빌드 지시문을 포함합니다:// go:build integrationgo test명령어에-tags=integration을 추가하여 실행할 수 있습니다.
테스트 파일의 빌드 지시문 상태를 테스트하려면 make check_test_directives를 사용할 수 있습니다.
커스텀 자격 증명으로 Shell 통합 테스트 실행#
자신의 자격 증명으로 이 테스트를 로컬에서 실행하려면 환경 변수를 설정하세요:
export GITLAB_TEST_TOKEN="your-access-token"
read_repository, read_api, 또는 api 권한 중 하나를 가진 개인 또는 그룹 액세스 토큰을 사용하세요.
gitlab-runner-pipeline-tests 하위 프로젝트에 접근 권한이 없는 경우, 토큰이 필요한 권한을 가진 자신의 프로젝트를 가리키도록 테스트 URL을 업데이트할 수 있습니다. 프로젝트는 비공개여야 하며 비공개 리포지터리를 서브모듈로 사용해야 합니다.
예를 들어 TestGitIncludePaths 테스트를 실행하려면:
go test -count=1 -v -run TestGitIncludePaths --tags=integration ./executors/shell
Windows가 아닌 환경에서 Windows용 개발#
Vagrantfile을 제공하여 Windows Server 2019 또는 Windows 10 인스턴스를 실행하는 데 도움을 드립니다. Vagrant 내에서 여러 머신을 사용하기 때문입니다.
다음이 필요합니다:
- Vagrant 설치.
- Virtualbox 설치.
- 컴퓨터에 약 30GB의 여유 하드 디스크 공간.
사용할 가상 머신은 사용 사례에 따라 다릅니다:
- Windows Server 머신에는 Docker가 사전 설치되어 있으며 Windows용 GitLab Runner를 개발할 때 항상 사용해야 합니다.
- Windows 10 머신은 일부 Windows 기능을 디버깅하는 데 도움이 될 수 있는 GUI가 있는 Windows 환경을 제공합니다. 중첩 가상화가 지원되지 않으므로 Windows 10 내에서 Docker를 실행할 수 없습니다.
vagrant up windows_10을 실행하면 Windows 10 머신이 시작됩니다. 다음을 수행하려면:
- Windows 10 머신에 SSH로 접속하려면
vagrant ssh windows_10을 실행하세요. - Windows 10 GUI에 액세스하려면
vagrant rdp windows_10을 실행하여 RDP를 통해 연결할 수 있으며, 로컬에 설치된 RDP 프로그램을 사용하여 머신에 연결됩니다.
두 머신 모두 GitLab Runner 소스 코드가 양방향으로 동기화되어 즐겨 사용하는 편집기로 머신에서 편집할 수 있습니다. 소스 코드는 $GOROOT 환경 변수 아래에서 찾을 수 있습니다. PowerShell을 사용할 때 전체 경로를 알기 위해 cd $Env:RUNNER_SRC를 사용할 수 있는 RUNNER_SRC 환경 변수가 있습니다.