• 권장 환경
• 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. 기여
• 윈도우즈에서 비-윈도우 환경으로 개발하기
• 다른 리소스

GitLab Runner 개발에 기여하기

GitLab Runner는 두 가지 모드에서 작동할 수 있는 Go 이진 파일입니다:

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

인스턴스 실행자 모드(1)에서 GitLab Runner를 개발하기 위해서는 작동하는 Go 환경만 필요합니다. 관리자 및 헬퍼 모드(2)에서 GitLab Runner를 개발하기 위해서는 Docker 빌드 환경도 설정해야 합니다. 또한, 관리자 또는 헬퍼를 Kubernetes에서 실행하려면 작동하는 클러스터가 필요합니다.

다음 지침은 asdf를 사용하여 Go 버전을 관리하고, Go 환경을 설정합니다. 이미 이를 가지고 있거나 다른 방법을 알고 계신다면 2단계(“의존성 및 Go 런타임 설치”)를 건너뛸 수 있습니다.

도커 및 Kubernetes를 제공하려면 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를 자동 크기 조정 모드(매니저 및 헬퍼)로 개발하는 경우 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 Engine은 미리 빌드된 이미지를 만들어 GitLab Runner에 통합하고 Docker 실행자를 사용할 때 로드하는 데 필요합니다. 로컬 Kubernetes 클러스터는 Kubernetes 실행자를 개발하는 데 도움이 됩니다. Rancher Desktop은 둘 다 제공합니다.

Rancher Desktop을 설치하려면 OS에 맞는 설치 지침을 따르세요.

참고: Rancher Desktop이 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를 실행하세요. 이 명령은 다음 작업을 수행합니다.

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 등)을 대체합니다. 이 새로운 메커니즘은 Pre-alpha 상태이며 활발하게 개발 중입니다. GitLab Runner에서 다음 두 라이브러리가 사용됩니다.

1. Taskscaler
2. Fleeting

HEAD 상태의 GitLab Runner를 사용하려면 이러한 라이브러리를 체크아웃할 필요는 없지만, 자동 스케일링 공간의 일부 개발은 해당 라이브러리에서 이루어질 수 있습니다. 또한 Taskscaler 및 Fleeting 외에도, 특정 클라우드 제공업체(Google Computer 또는 AWS EC2 등)에 GitLab Runner를 적응시키는 여러 Fleeting 플러그인이 있습니다.

상세한 지침서는 각 플러그인과 함께 제공되지만, 일반적인 지침서는 아래와 같습니다.

플러그인 빌드

플러그인을 실행하려면 실행 가능한 이진 파일을 생성하고 시스템의 PATH에 배치하세요.

이진 파일을 생성하려면 $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"                                 # 1. 위에서 빌드한 Fleeting 플러그인 이름.
    [runners.autoscaler.plugin_config]
      credentials_file = "/Users/josephburnett/.aws/credentials".  # 2. Autoscaling 그룹(ASG)을 확장할 수 있는 자격 증명.
      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)에 대한 테스트가 포함되어 있습니다. 실행자에 대한 테스트에는 로컬 컴퓨터에 특정 이진 파일이 설치되어 있어야 합니다. 이진 파일들 중 일부는 모든 운영 체제에 설치할 수 없는 경우도 있습니다. 만약 이진 파일이 설치되어 있지 않으면 해당 이진 파일이 필요한 테스트는 건너뛰게 됩니다.

다음은 설치할 수 있는 이진 파일입니다:

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 타겟은 또한 대부분의 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.

윈도우즈에서 비-윈도우 환경으로 개발하기

우리는 Vagrantfile을 제공하여 여러 대의 머신을 사용하는 multiple machines을 Vagrant 내에서 실행할 수 있도록 도와줍니다.

다음 사항이 필요합니다.

• Vagrant이 설치되어 있어야 합니다.
• Virtualbox이 설치되어 있어야 합니다.
• 컴퓨터에 약 30GB의 무료 하드 디스크 공간이 있어야 합니다.

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

• 윈도우 서버 머신에는 Docker가 사전 설치되어 있으며, Windows용 GitLab Runner를 개발할 때 항상 사용해야 합니다.
• Windows 10 머신은 때로는 윈도우 환경에서 GUI를 가지고 있는 것이 몇 가지 윈도우 기능을 디버깅하는 데 도움이 될 수 있도록 여러분을 위해 제공됩니다. 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을 사용할 때 전체 경로를 파악할 수 있는 RUNNER_SRC 환경 변수를 갖고 있으므로, cd $Env:RUNNER_SRC를 사용할 수 있습니다.

다른 리소스

1. GitLab Runner 병합 요청 확인하기
2. 새로운 윈도우 버전 지원 추가
3. Runner 그룹 - 팀 리소스