- 추천 환경
- 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는 작업을 로컬에서 실행합니다(“instance” executor).
- Runner 매니저는 작업을 autoscaled 환경으로 위임하며, 이때 GitLab Runner Helper가 artifact를 가져옵니다.
인스턴스 executor 모드(1)에서 GitLab Runner를 개발하는 경우, 작동하는 Go 환경이 필요합니다. Manager 및 Helper 모드(2)의 GitLab Runner를 개발하는 경우 Docker 빌드 환경이 필요합니다. 또한, Manager 또는 Helper를 Kubernetes에서 실행하려면 작동 중인 클러스터가 필요합니다.
다음 지침은 Go 환경을 설정하고 asdf를 사용하여 Go 버전을 관리합니다. 이미 해당 환경을 사용하거나 어떻게 하는지 알고 있는 경우, 2단계(“의존성 및 Go 런타임 설치”)를 건너뛸 수 있습니다.
도커 및 Kubernetes를 제공하려면, 3단계에서 Rancher Desktop을 설정합니다. 하나 이상이 필요하지 않은 경우, 3단계(“Rancher Desktop 설치”)를 건너뛰거나 Rancher Desktop에서 k3s (Kubernetes)를 비활성화합니다.
추천 환경
개발을 위해 Go 및 Rancher Desktop을 설치할 추천 환경은 로컬 노트북 또는 데스크탑입니다. 클라우드에서 Rancher Desktop을 실행하기 위해 중첩 가상화를 사용할 수 있지만 설정하기 더 복잡합니다.
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 모드(Manager 및 Helper)로 개발하는 경우, 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.9.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.9.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.9.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.9.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
pkg install go-1.21.9 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
3. Rancher Desktop 설치
Docker Engine은 GitLab Runner에 내장된 사전 빌드된 이미지를 만들기 위해 필요하며, Docker executor를 사용할 때 로드됩니다. 로컬 Kubernetes 클러스터는 Kubernetes executor를 개발하는 데 도움이 됩니다. Rancher Desktop은 둘 다 제공합니다.
Rancher Desktop을 설치하려면, 사용 중인 OS에 따라 설치 지침을 따르세요.
dockerd (moby)가 아니라 containerd를 사용하도록 구성되었는지 확인하세요.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 Helper 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부터)
다음 Runner Auto-scaling Architecture은 모든 환경과 함께 작동할 새로운 자동 스케일링 기구를 추가합니다. 이것은 현재의 모든 자동 스케일링 기구(e.g. Docker Machine)를 대체합니다. 이 새로운 기구는 사전 알파 상태이며 활발하게 개발 중입니다. GitLab Runner에서 사용되는 두 개의 새로운 라이브러리가 있습니다.
HEAD에서 GitLab Runner를 사용하려면 이러한 라이브러리를 확인할 필요는 없지만, 자동 스케일링 공간에서 일부 개발이 진행될 수 있습니다. 또한 Taskscaler 및 Fleeting 외에도 특정 클라우드 제공업체(e.g. Google Computer 또는 AWS EC2)에 GitLab Runner를 적응시키는 여러 Fleeting 플러그인이 있습니다. 위에 작성된 지침(“GitLab Runner 복제”)은 코드를 체크아웃하는 방법을 보여주며, 비디오(“Runner Shorts”)는 그것을 사용하는 방법을 보여줍니다. 이러한 지침은 플러그인을 사용하는 방법을 보여줍니다.
각 플러그인은 바이너리를 빌드하고 기본 인스턴스 그룹을 구성하는 방법에 대한 지침이 포함됩니다. 이 작업은 이 이슈에서 진행 중입니다. 관련되는 표준 빌드 및 구성 지침은 각 플러그인과 함께 제공되지만 그 동안 여기에 몇 가지 일반적인 지침을 제공합니다.
플러그인 빌드
GitLab Runner를 플러그인과 함께 실행하려면 실행 가능한 이진 파일을 생성하고 시스템의 PATH에 배치하세요.
이진 파일을 생성하려면 $GOPATH/bin이 PATH에 있는지 확인한 다음, go install을 사용하세요.
각 플러그인에는 ./cmd/<plugin-name>으로의 경로가 포함되어 있습니다. 예를 들어, 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 그룹 (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
GitLab Runner를 SIGTERM으로 종료하면 일부 프로세스가 여전히 남아 있을 수 있습니다. 대신에 SIGQUIT로 종료하세요.
ASG는 자동 스케일링이 비활성화되어야 합니다. GitLab Runner가 자동 스케일링을 Taskscaler 라이브러리를 통해 처리합니다.
7. 로컬에서 테스트 스위트 실행
GitLab Runner 테스트 스위트는 “core” 테스트와 executor용 테스트로 구성됩니다. Executor용 테스트에는 로컬 머신에 설치된 특정 이진 파일이 필요합니다. 이들 중 일부 이진 파일은 모든 운영 체제에 설치할 수 없습니다. 이 바이너리 중 하나가 설치되어 있지 않으면 해당 이진 파일을 필요로 하는 테스트를 건너뛸 것입니다.
여기에서 설치할 수 있는 이진 파일입니다:
- VirtualBox 및 Vagrant; Vagrant Parallels 플러그인도 필요합니다.
- 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 타겟
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를 사용하여 의존성을 관리합니다.
버전 태그가 사용 가능한 경우에는 상류 기본 브랜치에서 의존성을 추가하지 마세요.
테스트
러너 코드베이스는 다음과 같이 단위 테스트와 통합 테스트를 구분합니다:
-
단위 테스트 파일은
_test.go접미사가 있으며 헤더에 다음을 포함합니다:// go:build !integration -
통합 테스트 파일은
_integration_test.go접미사가 있으며 헤더에 다음을 포함합니다:// go:build integration-tags=integration를go test명령에 추가하여 실행할 수 있습니다.
테스트 파일에서 테스트 지시문의 상태를 테스트하려면 make check_test_directives를 사용할 수 있습니다.
Windows 환경에서 Windows에 대한 개발
이 링크에서 Windows Server 2019 또는 Windows 10 인스턴스를 실행하는 데 도움이 되는 Vagrantfile을 제공합니다. 왜냐하면 Vagrant 내에 다중 머신을 사용하고 있기 때문입니다.
다음이 필요합니다:
- Vagrant가 설치되어 있어야 합니다.
- Virtualbox가 설치되어 있어야 합니다.
- 컴퓨터에 약 30GB의 무료 하드 디스크 공간이 있어야 합니다.
어떤 가상 머신을 사용할지는 사용 사례에 따라 다릅니다:
- Windows Server 머신에는 Docker가 미리 설치되어 있으며 Windows용 GitLab Runner를 개발할 때 항상 사용해야 합니다.
- Windows 10 머신은 때로는 GUI가 있는 Windows 환경을 가지고 있어서 Windows의 일부 기능을 디버깅하는 데 도움이 되므로 사용할 수 있습니다. Windows 10 내에서 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을 사용할 때 cd $Env:RUNNER_SRC를 사용하여 전체 경로를 확인할 수 있는 RUNNER_SRC 환경 변수가 있습니다.
도움말