• 권장 환경
• 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 환경에서 Windows용 개발하기
• 기타 리소스

GitLab Runner 개발에 기여하기

GitLab Runner은 두 가지 모드로 작동할 수 있는 Go 이진 파일입니다.

1. GitLab Runner는 작업을 로컬에서 실행합니다 (“인스턴스” 실행기).
2. Runner 관리자가 작업을 자동으로 확장되는 환경으로 위임하며 이때 GitLab Runner Helper를 사용하여 아티팩트를 가져올 수 있습니다.

인스턴스 실행기 모드(1)에서 GitLab Runner를 개발하려면 작동 중인 Go 환경만 필요합니다. 매니저 및 Helper 모드(2)에서 GitLab Runner를 개발하려면 Docker 빌드 환경도 필요합니다. 또한 매니저 또는 Helper를 Kubernetes에서 실행하려면 작동 중인 클러스터가 필요합니다.

다음 지침은 Go 환경을 설정하는데 asdf를 사용합니다. 이미 이를 사용하고 있거나 자신이 무엇을 하는지 알고 있다면 2단계(“의존성 및 Go 런타임 설치”)를 건너뛸 수 있습니다.

도커와 쿠버네티스를 제공하려면 3단계에서 Rancher Desktop을 설정합니다. 이를 원하지 않는다면 또는 둘 중 하나만 필요하다면 3단계(“Rancher Desktop 설치”)를 건너뛰거나 Rancher Desktop에서 k3s (Kubernetes)를 비활성화하세요.

권장 환경

개발을 위해 Go와 Rancher Desktop을 설치할 권장 환경은 로컬 노트북이나 데스크탑입니다. Rancher Desktop을 클라우드에서 실행하기 위해 중첩 가상화를 사용할 수 있으나(VM에서 k3s를 실행함) 설정이 더 까다로울 수 있습니다.

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를 자동으로 확장된 모드(매니저 및 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 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 엔진은 GitLab Runner에 포함되는 사전 빌드된 이미지를 생성하는 데 필요하며 Docker 실행기를 사용할 때 로드됩니다. 로컬 Kubernetes 클러스터는 Kubernetes 실행기를 개발하는 데 도움이 됩니다. 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

HEAD에서 GitLab Runner를 사용하지 않는 한, 이러한 라이브러리에서 자동 스케일링 공간의 일부 개발이 진행될 수 있습니다. 또한 Taskscaler 및 Fleeting과 함께 특정 클라우드 제공업체(Google Compute 또는 AWS EC2 등)에 GitLab Runner를 적응시키는 여러 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 executor를 지정합니다. 또한 plugin_config 및 connector_config에 Instance 그룹, 해당 위치 및 기본 인스턴스에 연결하는 방법에 대한 세부 정보가 지정됩니다. GitLab Runner는 Instance 그룹을 찾아 초기 일시 중단된 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".  # 자동 스케일링 그룹(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를 위한 테스트에는 로컬 컴퓨터에 특정한 바이너리가 설치되어 있어야 합니다. 모든 운영 체제에 바이너리를 설치할 수 없는 경우도 있습니다. 만약 바이너리가 설치되어 있지 않다면, 해당 바이너리를 필요로 하는 테스트는 건너뜁니다.

설치할 수 있는 바이너리는 다음과 같습니다:

1. VirtualBox 및 Vagrant; Vagrant Parallels 플러그인도 필요합니다.
2. kubectl 및 minikube
3. Parallels Pro 또는 Business edition
4. 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 타겟은 parallel_test_execute용 -ldflags도 자동으로 삽입하며, 이는 대부분의 CI/CD 작업에서 가장 일반적으로 사용됩니다.

사용자 정의 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.
• 설치된 Virtualbox.
• 컴퓨터에 약 30GB의 무료 하드 디스크 공간.

어떤 가상 머신을 사용할지는 사용 사례에 따라 다릅니다:

• Windows Server 머신에는 사전 설치된 Docker가 있으며, Windows용 GitLab Runner 개발 시 항상 사용해야 합니다.
• Windows 10 머신은 때로는 일부 Windows 기능을 디버깅하는 데 도움이 되는 GUI가 있는 Windows 환경을 둘 수 있습니다. Windows 10의 내포된 가상화가 지원되지 않기 때문에 Windows 10에서 Docker를 실행할 수 없다는 점에 유의하십시오.

vagrant up windows_10을 실행하여 Windows 10 머신을 시작할 수 있습니다. 그런 다음:

• Windows 10 머신 내부로 SSH에 접속하려면 vagrant ssh windows_10을 실행합니다.
• Windows 10의 GUI에 액세스하려면 로컬에 설치된 RDP 프로그램을 사용하여 실행하면 됩니다.

두 머신 모두 GitLab Runner 소스 코드를 양방향으로 동기화하여 좋아하는 편집기에서 개발할 수 있도록 합니다. 소스 코드는 $GOROOT 환경 변수 아래에서 찾을 수 있습니다. PowerShell을 사용할 때는 cd $Env:RUNNER_SRC를 사용할 수 있습니다.

기타 리소스

1. GitLab Runner MR 검토
2. 새 Windows 버전 지원 추가
3. Runner 그룹 - 팀 리소스