• 권장 환경
• Runner Shorts 비디오 튜토리얼
• 1. GitLab Runner 클론하기
• 2. 종속성 및 Go 런타임 설치
• 3. Rancher Desktop 설치
• 4. GitLab Runner 종속성 설치
• 5. GitLab Runner 빌드
• 6. GitLab Runner 실행
  • Docker 이미지 빌드하기
  • GitLab Runner의 새로운 자동 확장 기능(Taskscaler) (15.6.0 이후)
    • 플러그인 빌드
    • 플러그인 사용
• 7. 로컬에서 테스트 스위트 실행
  • Kubernetes 통합 테스트
• 8. 선택한 버전의 헬퍼 이미지로 테스트 실행
  • Make 타겟
  • 사용자 정의 go test 인수
  • GoLand에서
  • 헬퍼 이미지
  • Kubernetes와 함께하는 헬퍼 이미지
• 9. 선택적 도구 설치
• 10. 기여하기
• 빌드 의존성 관리
• 테스트
• 비윈도우 환경에서 Windows 개발하기
• 기타 리소스

GitLab Runner 개발에 기여하기

GitLab Runner는 두 가지 모드에서 작동할 수 있는 Go 바이너리입니다:

1. GitLab Runner가 로컬에서 작업을 실행하는 모드(“인스턴스” 실행기).
2. Runner 관리자가 GitLab Runner Helper를 사용하여 아티팩트를 가져오는 자동 조정 환경에 작업을 위임하는 모드.

GitLab Runner를 인스턴스 실행기 모드(1)로 개발하기 위해 필요한 유일한 설정은 작동하는 Go 환경입니다.

GitLab Runner를 관리자 및 헬퍼 모드(2)로 개발하기 위해서는 Docker 빌드 환경도 필요합니다.

또한, Kubernetes에서 관리자를 실행하려면 작동하는 클러스터가 필요합니다.

다음 지침은 Go 버전을 관리하기 위해 asdf를 사용하여 Go 환경을 설정합니다. 이미 이 설정이 되어 있거나 다른 방법으로 알고 있다면 2단계(“종속성 및 Go 런타임 설치”)를 건너뛸 수 있습니다.

로컬에서 Docker와 Kubernetes를 제공하기 위해 3단계에서는 Rancher Desktop을 설정합니다. 하나 또는 둘 다 필요하지 않다면 3단계(“Rancher Desktop 설치”)를 건너가거나 Rancher Desktop에서 k3s(Kubernetes)를 단순히 비활성화하면 됩니다.

권장 환경

개발을 위해 Go와 Rancher Desktop을 설치할 권장 환경은 로컬 노트북 또는 데스크탑입니다. 클라우드에서 Rancher Desktop을 실행하기 위해 중첩 가상화(nested-virtualization)를 사용할 수 있지만, 이를 설정하는 것이 더 까다롭습니다.

Runner Shorts 비디오 튜토리얼

설정하고 변경하는 방법에 대한 Runner Shorts(~20분 비디오)를 따를 수도 있습니다:

1. 시작하기 전에 권장 환경 섹션을 읽어보세요.
2. GitLab Runner 개발 환경 설정하기
3. GitLab Runner의 코드 워크스루
4. GitLab Runner 변경 사항을 로컬에서 만들고 테스트하기

1. GitLab Runner 클론하기

git clone https://gitlab.com/gitlab-org/gitlab-runner.git

자동 조정 모드(관리자 및 헬퍼)로 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 프로젝트는 asdf를 사용하여 종속성을 관리합니다.

개발 환경을 설정하는 가장 간단한 방법은 asdf를 사용하는 것입니다.

cd gitlab-runner
asdf plugin add golang
asdf plugin add vale
asdf plugin add yq
asdf install

sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.22.7.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.22.7.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.22.7.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.22.7.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.22.7 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 Engine은 GitLab Runner에 내장된 미리 구축된 이미지를 생성하고 Docker executor를 사용할 때 로드하는 데 필요합니다. 로컬 Kubernetes 클러스터는 Kubernetes executor 개발에 유용합니다. Rancher Desktop은 둘 다 제공합니다.

Rancher Desktop을 설치하려면, 해당 OS에 대한 설치 지침을 따르세요.

Rancher Desktop이 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는 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를 실행하세요. 그러면 다음을 수행합니다:

1. gitlab-runner-helper를 빌드하고 이를 기반으로 도우미 Docker 이미지를 생성합니다.
2. linux/amd64용으로 GitLab Runner를 컴파일합니다.
3. Runner용 DEB 패키지를 빌드합니다. 공식 GitLab Runner 이미지는 Alpine 및 Ubuntu를 기반으로 하며, Ubuntu 이미지 빌드는 DEB 패키지를 사용합니다.
4. gitlab/gitlab-runner 이미지의 Alpine 및 Ubuntu 버전을 빌드합니다.

GitLab Runner의 새로운 자동 확장 기능(Taskscaler) (15.6.0 이후)

다음 Runner 자동 확장 아키텍처는 모든 환경에서 작동할 새로운 자동 확장 메커니즘을 추가합니다.
현재의 모든 자동 확장 메커니즘(예: Docker Machine)을 대체할 것입니다.
이 새로운 메커니즘은 사전 알파 상태에 있으며, 활발히 개발 중입니다.
GitLab Runner에서 사용되는 두 개의 새로운 라이브러리가 있습니다:

1. Taskscaler
2. Fleeting

GitLab Runner를 HEAD로 사용하기 위해 이러한 라이브러리를 체크아웃할 필요는 없지만, 자동 확장 영역의 일부 개발이 그곳에서 진행될 수 있습니다.
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

asdf로 Go 버전을 관리하는 경우, 바이너리가 생성된 후 이 명령을 실행합니다:

asdf 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".  # 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 테스트 스위트는 “코어” 테스트와 실행기 테스트로 구성됩니다.

실행기 테스트는 로컬 컴퓨터에 특정 바이너리가 설치되어 있어야 합니다. 이러한 바이너리 중 일부는 모든 운영 체제에 설치할 수 없습니다. 바이너리가 설치되어 있지 않으면 이 바이너리를 요구하는 테스트는 건너뛰게 됩니다.

다음은 설치할 수 있는 바이너리입니다:

1. VirtualBox 및 Vagrant; Vagrant Parallels 플러그인도 필요합니다.
2. kubectl 및 minikube
3. Parallels Pro 또는 Business 에디션
4. 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. 선택한 버전의 헬퍼 이미지로 테스트 실행

헬퍼 내부에서 기능을 개발하는 경우, 변경된 사항을 포함하는 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. 선택적 도구 설치

• golangci-lint를 설치합니다. 이는 make lint 타겟에서 사용됩니다.
• markdown-lint 및 vale를 설치합니다. 이들은 make lint-docs 타겟에서 사용됩니다.

도구가 누락된 경우 Makefile 타겟을 실행하면 설치 지침이 표시됩니다.

10. 기여하기

gitlab-runner 코드를 해킹하기 시작할 수 있습니다.

코드를 편집하고 디버그하기 위한 IDE가 필요하다면 사용할 수 있는 몇 가지 무료 추천 사항이 있습니다:

• JetBrains GoLand IDE.
• Visual Studio Code를 사용하여 추천 확장을 사용할 수 있습니다. 이는 .vscode/extensions.json에 위치합니다.

빌드 의존성 관리

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 개발하기

우리는 Vagrantfile를 제공하여 Windows Server 2019 또는 Windows 10 인스턴스를 실행하는 데 도움을 주며, Vagrant 내에서 여러 머신을 사용하고 있습니다.

다음은 필요합니다:

• Vagrant 설치.
• Virtualbox 설치.
• 컴퓨터에 약 30GB의 여유 하드 디스크 공간.

사용할 가상 머신은 사용 사례에 따라 다릅니다:

• Windows Server 머신은 Docker가 미리 설치되어 있으며 GitLab Runner를 Windows에서 개발할 때 항상 사용해야 합니다.
• Windows 10 머신은 GUI가 있는 Windows 환경을 제공하며, 때때로 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 프로그램을 사용해 머신에 연결할 수 있습니다.

두 머신 모두 GitLab Runner 소스 코드는 양방향으로 동기화되어 있어 좋아하는 편집기로 컴퓨터에서 편집할 수 있습니다. 소스 코드는 $GOROOT 환경 변수 아래에 있습니다. 전체 경로를 찾으려면 RUNNER_SRC 환경 변수를 사용할 수 있으며, PowerShell을 사용할 경우 cd $Env:RUNNER_SRC를 사용할 수 있습니다.

기타 리소스

1. GitLab Runner 병합 요청 검토하기
2. 새 Windows 버전 지원 추가하기
3. Runner 그룹 - 팀 리소스