- 권장 환경
- Runner Shorts 동영상 자습서
- 1. GitLab Runner 복제하기
- 2. 의존성 및 Go 런타임 설치
- 3. Rancher Desktop 설치
- 4. GitLab Runner 의존성 설치
- 5. GitLab Runner 빌드
- 6. GitLab Runner 실행
- 7. 지역에서 테스트 스위트 실행
- 8. 선택한 도우미 이미지 버전으로 테스트 실행
- 9. 선택적인 도구 설치
- 10. 기여
- 빌드 의존성 관리
- 테스트
- 비-Windows 환경에서 Windows용 개발
- 기타 리소스
GitLab Runner 개발에 기여하기
GitLab Runner는 두 가지 모드에서 작동할 수 있는 Go 이진 파일입니다.
- GitLab Runner는 작업을 로컬에서 실행합니다(“인스턴스” 실행자).
- Runner 매니저는 작업을 autoscaled 환경에 위임하고, GitLab Runner Helper를 사용하여 artifact를 가져옵니다.
인스턴스 실행자 모드(1)에서 GitLab Runner를 개발하기 위해 필요한 것은 작동하는 Go 환경뿐입니다. 매니저 및 도우미 모드(2)로 GitLab Runner를 개발하기 위해서는 Docker 빌드 환경이 필요합니다. 또한 쿠버네티스에서 매니저나 도우미를 실행하려면 작동하는 클러스터가 필요합니다.
다음 안내는 Go 환경을 설정하는 방법을 제공하며, Go 버전 관리를 위해 asdf를 사용합니다. 이미 이를 가지고 있거나 다른 방법을 알고 있다면 2단계(“의존성 및 Go 런타임 설치”)를 건너뛸 수 있습니다.
로컬 개발을 위해 Go 및 Rancher Desktop을 설치하는 것이 권장됩니다. Rancher Desktop을 사용하여 Docker 및 Kubernetes를 제공할 수 있습니다.
권장 환경
개발을 위해 Go 및 Rancher Desktop을 설치하는 권장 환경은 로컬 노트북 또는 데스크탑입니다. Rancher Desktop을 클라우드에서 실행하기 위해 중첩 가상화(nested-virtualization)를 사용할 수 있지만 이러한 설정은 조금 까다롭습니다.
Runner Shorts 동영상 자습서
Runner Shorts(약 20분 동영상)를 따라가면서 설정 및 변경 작업을 진행할 수 있습니다:
- 시작하기 전에 권장 환경 섹션을 읽어주세요.
- GitLab Runner 개발 환경 설정
- GitLab Runner 코드 살펴보기
- 로컬에서 GitLab Runner 변경사항 만들고 테스트하기
1. GitLab Runner 복제하기
git clone https://gitlab.com/gitlab-org/gitlab-runner.git
GitLab Runner를 autoscaled 모드(매니저 및 도우미)로 개발하는 경우, 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 프로젝트는 의존성을 관리하기 위해 asdf를 사용합니다. 개발 환경을 설정하는 가장 간단한 방법은 asdf를 사용하는 것입니다.
cd gitlab-runner
asdf plugin add golang
asdf plugin add vale
asdf install
sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.21.7.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
sudo yum install mercurial wget make
sudo yum groupinstall 'Development Tools'
wget https://storage.googleapis.com/golang/go1.21.7.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
바이너리 패키지 사용:
wget https://storage.googleapis.com/golang/go1.21.7.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
설치 패키지 사용:
wget https://storage.googleapis.com/golang/go1.21.7.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
pkg install go-1.21.7 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
3. Rancher Desktop 설치
Docker 엔진은 GitLab Runner에 내장된 사전 빌드된 이미지를 생성하는 데 필요하며, Docker 실행자를 사용할 때 로컬 Kubernetes 클러스터는 유용합니다. Rancher Desktop은 둘 다 제공합니다.
Rancher Desktop을 설치하려면 OS에 따라 설치 지침을 따르세요.
dockerd (moby)를 사용하도록 구성하십시오.4. GitLab Runner 의존성 설치
make deps
asdf reshim
FreeBSD의 경우 gmake deps를 사용하세요.
5. GitLab Runner 빌드
Go 도구 체인을 사용하여 GitLab Runner를 컴파일하세요:
make runner-and-helper-bin-host
make runner-and-helper-bin-host는 추가로 Runner 도우미 Docker 아카이브 의존성을 빌드하는 make runner-bin-host의 상위 집합입니다.
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를 빌드하고 이를 사용하여 도우미 Docker 이미지를 생성합니다. -
linux/amd64용 GitLab Runner를 컴파일합니다. - Runner를 위해 DEB 패키지를 빌드합니다. 공식 GitLab Runner 이미지는 Alpine 및 Ubuntu를 기반으로 하며, Ubuntu 이미지 빌드에는 DEB 패키지가 사용됩니다.
-
gitlab/gitlab-runner이미지의 Alpine 및 Ubuntu 버전을 빌드합니다.
GitLab Runner의 새로운 자동 스케일링 (Taskscaler) (15.6.0부터)
다음 Running Auto-scaling Architecture은 모든 환경에서 작동할 새로운 오토스케일링 메커니즘을 추가했습니다. 이 것은 모든 현재의 오토스케일링 메커니즘 (예: Docker Machine)을 대체할 것입니다. 이 새로운 메커니즘은 사전 알파 상태에 있으며 활발히 개발 중입니다. GitLab Runner에서 사용되는 두 가지 새로운 라이브러리가 있습니다:
이러한 라이브러리를 확인하지 않고도 GitLab Runner를 최신 버전으로 사용할 수 있지만, 오토스케일링 공간의 일부 개발이 여기에서 일어날 수 있습니다. 또한 Taskscaler와 Fleeting 외에도 GitLab Runner를 특정 클라우드 제공업체에 맞게 조정하는 Fleeting 플러그인이 여럿 있습니다 (예: Google Computer 또는 AWS EC2). 위에 쓰인 매뉴얼(“GitLab Runner 복제”)는 코드를 확인하는 방법을 보여주고 있으며 비디오(“Runner Shorts”)는 그것을 사용하는 방법을 보여줍니다. 이러한 매뉴얼는 플러그인을 사용하는 방법을 보여줍니다.
각 플러그인은 실행 파일을 생성하고 시스템의 PATH에 배치하여 GitLab Runner를 실행할 수 있습니다.
실행 파일을 생성하려면, $GOPATH/bin이 PATH에 있는지 확인한 후 go install을 사용하십시오.
각 플러그인은 ./cmd/<플러그인-이름> 경로를 포함합니다. 예를 들어, fleeting-plugin-aws 디렉터리에서:
cd cmd/fleeting-plugin-aws/
go install
만약 asdf로 go 버전을 관리 중이라면, 실행 파일을 생성한 후에 이 명령어를 실행하십시오:
asdf reshim
플러그인을 사용하세요
플러그인이 있는 GitLab Runner는 보통대로 시작되지만 instance executor를 지정합니다.
그리고 plugin_config 및 connector_config에 인스턴스 그룹, 그 위치 및 기본 인스턴스에 대한 연결 방법에 대한 세부 정보를 지정합니다.
GitLab Runner는 인스턴스 그룹을 찾아 초기 대기 중인 VM의 수를 생성해야 합니다.
구성된 인스턴스 러너에서 작업을 수행하면 fleeting-plugin-aws 플러그인에서 AWS 서비스 호출을 통해 실행 중인 VM을 사용하고 대체해야 합니다.
[[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". # Autoscaling 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 테스트 스위트는 “core” 테스트와 executor용 테스트로 구성됩니다. Executor용 테스트에는 로컬 머신에 설치된 특정 이진 파일이 필요합니다. 모든 운영 체제에 모든 이진 파일을 설치할 수 없습니다. 만약 이진 파일이 설치되지 않았다면, 이진 파일이 설치되어 있지 않은 테스트는 건너뜁니다.
다음은 설치할 수 있는 이진 파일입니다:
- VirtualBox 및 Vagrant; Vagrant Parallels plugin도 필요합니다.
- kubectl 및 minikube
- Parallels Pro 또는 Business edition
- PowerShell
이진 파일을 설치한 후 다음을 실행하세요:
make development_setup
테스트를 실행하려면 다음을 실행하세요:
make test
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. 선택한 도우미 이미지 버전으로 테스트 실행
도우미 내에서 기능을 개발하는 경우, 최신 변경 사항이 포함된 Docker 이미지 버전으로 테스트를 실행하려고 할 것입니다.
-ldflags를 전달하지 않고 테스트를 실행한다면, version.go의 기본 버전은 development입니다.
이것은 러너가 latest 태그를 가진 도우미 이미지를 기본으로 가져오도록 하는 것입니다.
대상 만들기
make 대상은 -ldflags를 자동으로 주입합니다. 다음 명령을 사용하여 모든 테스트를 실행할 수 있습니다:
make simple-test
make 대상은 또한 CI/CD 작업에서 가장 일반적으로 사용되는 parallel_test_execute에 대한 -ldflags를 자동으로 주입합니다.
사용자 지정 go test 인수
더 맞춤화된 go test 명령이 필요한 경우 make 대상으로 print_ldflags를 사용할 수 있습니다:
go test -ldflags "$(make print_ldflags)" -run TestDockerCommandBuildCancel -v ./executors/docker/...
GoLand에서
현재 GoLand는 동적 Go 도구 인수를 지원하지 않으므로 먼저 make print_ldflags를 실행한 다음 설정에 붙여넣어야 합니다.
-s -w)를 제거해야 합니다.도우미 이미지
다음과 같이 최신 버전의 도우미 이미지를 빌드하세요:
make helper-dockerarchive-host
그런 다음 이미지를 사용할 준비가 됩니다:
REPOSITORY TAG IMAGE ID CREATED SIZE
gitlab/gitlab-runner-helper x86_64-a6bc0800 f10d9b5bbb41 32 seconds ago 57.2MB
Kubernetes와 함께 사용하는 도우미 이미지
로컬 Kubernetes 클러스터를 실행하는 경우 클러스터의 Docker 데몬을 재사용해야 합니다. 예를 들어, minikube를 사용할 때:
eval $(minikube docker-env)
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를 사용하여 의존성을 관리합니다.
버전 태그를 사용할 수 있는 경우 상위 스트림 기본 브랜치에서 의존성을 추가하지 마세요.
테스트
Runner 코드베이스는 단위 및 통합 테스트를 다음과 같이 구분합니다:
-
단위 테스트 파일은
_test.go접미사가 있으며 헤더에 다음 빌드 지시문을 포함합니다:// go:build !integration -
통합 테스트 파일은
_integration_test.go접미사가 있으며 헤더에 다음 빌드 지시문을 포함합니다:// go:build integration이를 실행하려면
go test명령에-tags=integration를 추가합니다.
테스트 파일의 빌드 지시문 상태를 테스트하려면 make check_test_directives를 사용할 수 있습니다.
비-Windows 환경에서 Windows용 개발
여기에서 Windows Server 2019 또는 Windows 10 인스턴스를 실행하는 데 도움이 되는 Vagrantfile을 제공합니다. 왜냐하면 Vagrant 내부에 여러 대기를 사용하기 때문입니다.
다음이 필요합니다:
- 설치된 Vagrant.
- 설치된 Virtualbox.
- 컴퓨터에 약 30GB의 무료 하드 디스크 공간.
어떤 가상 머신을 사용할지는 사용 사례에 따라 다릅니다:
- Windows Server 기계에는 Docker가 사전 설치되어 있으며 항상 Windows용 GitLab Runner 개발 시 사용해야 합니다.
- Windows 10 기계는 때로는 Windows 특정 기능을 디버깅하는 데 도움이 되는 GUI가 있는 Windows 환경을 제공합니다. Windows 10에서는 중첩 가상화가 지원되지 않기 때문에 Windows 내에서 Docker를 실행할 수 없습니다.
vagrant up windows_10 명령을 실행하면 Windows 10 기계를 시작합니다. 그런 다음:
- Windows 10 기계 내부에서 SSH를 실행하려면
vagrant ssh windows_10를 실행합니다. - Windows 10의 GUI에 액세스하려면 로컬로 설치된 RDP 프로그램을 사용하여
vagrant rdp windows_10을 실행하여 기계에 연결합니다.
양쪽 기계에서 GitLab Runner 소스 코드는 양방향으로 동기화되어 즐겨 사용하는 편집기에서 로컬 컴퓨터에서 편집할 수 있습니다. 소스 코드는 $GOROOT 환경 변수 아래에서 찾을 수 있습니다. 사용 가능한 PowerShell에서 $Env:RUNNER_SRC를 사용하여 전체 경로를 찾을 수 있습니다.
도움말