GitLab Runner開発に貢献します。

GitLab Runnerは2つのモードでオペレーションできるGoバイナリです：

  1. GitLab Runnerはローカルでジョブを実行します（”インスタンス “エクゼキュータ）。
  2. GitLab Runner Helperを使ってアーティファクトをプルするオートスケール環境にジョブを委譲するRunnerマネージャ。

インスタンスエグゼキューターモード(1)でGitLab Runnerを開発する場合、必要なセットアップは動作するGo環境のみです。Manager and Helperモード（2）でGitLab Runnerを開発する場合、Dockerビルド環境が必要です。さらにKubernetesでManagerやHelperを実行するには、動作するクラスターが必要です。

以下の手順では、asdf を使って Go バージョンを管理しながら Go 環境をセットアップします。すでにこの方法をお持ちの場合や、自分が何をしているかわかっている場合は、ステップ2（「依存関係とGoランタイムのインストール」）をスキップできます。

DockerとKubernetesをローカルに提供するために、ステップ3ではRancher Desktopを設定します。どちらか、または両方が不要な場合は、ステップ3（「Rancher Desktopをインストールする」）をスキップするか、Rancher Desktopでk3s （Kubernetes）を無効にするだけです。

開発のためにGoとRancher Desktopをインストールする推奨環境は、ローカルのラップトップまたはデスクトップです。ネストされた仮想化を使用してクラウドで Rancher Desktop を実行することも可能です（k3s を VM で実行します）が、セットアップが面倒です。

Runner Shorts ビデオチュートリアル

Runnerショートビデオ（～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をオートスケールモード（ManagerとHelper）で開発する場合、TaskscalerやFleeting、関連プラグインを1つ以上チェックアウトするとよいでしょう。1つのパッケージのローカルの変更を他のパッケージから見えるようにするには、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 を使うことです。

asdf
cd gitlab-runner
asdf plugin add golang
asdf install
Debian/Ubuntu
sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.20.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
CentOS
sudo yum install mercurial wget make
sudo yum groupinstall 'Development Tools'
wget https://storage.googleapis.com/golang/go1.20.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
macOS

バイナリパッケージを使う

wget https://storage.googleapis.com/golang/go1.20.5.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.20.5.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
FreeBSD
pkg install go-1.20.5 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"

3.Rancher Desktopのインストール

Docker Engineは、GitLab Runnerに組み込まれ、Docker Executorを使用する際にロードされるビルド済みイメージを作成するために必要です。Kubernetes executorを開発するには、ローカルのKubernetesクラスターが便利です。Rancher Desktopはその両方を提供します。

Rancher Desktopをインストールするには、お使いのOSのインストール手順に従ってください。

note
Rancher Desktopは、containerdではなく、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 をビルドし、そこからhelper Dockerイメージを作成します。
  2. GitLab Runner forlinux/amd64 をコンパイルします。
  3. Runner用のDEBパッケージをビルドします。公式の GitLab Runner イメージは Alpine と Ubuntu をベースにしており、Ubuntu イメージのビルドには DEB パッケージが使われています。
  4. Alpine と Ubuntu バージョンのgitlab/gitlab-runner イメージをビルドします。

GitLab Runnerの新しい自動スケーリング（Taskscaler）（15.6.0以降）

Next Runner Auto-scaling Architectureは、すべての環境で動作するオートスケールのための新しいメカニズムを追加します。これは現在のすべてのオートスケーリングメカニズム（Docker Machineなど）を置き換えるものです。この新しいメカニズムはプレアルファの状態で、活発に開発されています。GitLab Runnerには2つの新しいライブラリがあります：

  1. Taskscaler
  2. Fleeting

HEADでGitLab Runnerを使うためにこれらのライブラリをチェックアウトする必要はありませんが、オートスケーリング領域でのいくつかの開発者はそこで行われるかもしれません。TaskscalerとFleetingに加えて、GitLab Runnerを特定のクラウドプロバイダー（Google ComputerやAWS EC2など）に適応させるFleeting Pluginがいくつかあります。上記の説明書（”Clone 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でバージョンを管理する場合は、バイナリが生成された後にこのコマンドを実行してください：

asdf reshim

プラグイン

GitLab Runner は通常の方法で起動しますが、instance の Executor を指定します。また、plugin_config とconnector_config でインスタンスグループとその場所、そして基盤となるインスタンスへの接続方法を指定します。GitLab Runnerはインスタンスグループを見つけ、アイドル状態のVMを初期数だけ作成します。設定されたインスタンスRunnerでジョブがピックアップされると、実行中の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 plugin name as built above [1].
    [runners.autoscaler.plugin_config]
      credentials_file = "/Users/josephburnett/.aws/credentials".  # Credentials which can scale an Autoscaling Group (ASG) [2].
      name = "jburnett-taskrunner-asg"                             # ASG name.
      project = "jburnett-ad8e5d54"                                # ASG project.
      region = "us-east-2"                                         # ASG region.
    [runners.autoscaler.connector_config]
      username = "ubuntu"                                          # ASG instance template username for login.
    [[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のテストスイートは、”コア “テストとエクゼキュータのためのテストから構成されています。エクゼキュータ用のテストは、特定のバイナリをローカルマシンにインストールする必要があります。これらのバイナリの中には、すべてのオペレーションシステムにインストールできないものもあります。バイナリがインストールされていない場合、そのバイナリを必要とするテストはスキップされます。

これらはインストール可能なバイナリです：

  1. VirtualBoxとVagrant。Vagrant Parallels プラグインも必要です。
  2. minikubeとkubectl
  3. Parallels Pro または Business エディション
  4. パワーシェル

バイナリをインストールしたら実行します：

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 になります。これは、Runnerがデフォルトでlatest タグを持つヘルパーイメージを取得することを意味します。

ターゲットの作成

make targets は-ldflags を自動的に注入します。を使ってすべてのテストを実行できます：

make simple-test

make ターゲットは-ldflags も注入します。parallel_test_execute は CI/CD ジョブで最もよく使われます。

カスタムgo test 引数

go test コマンドをよりカスタマイズしたい場合は、print_ldflags をmake のターゲットとして使用できます：

go test -ldflags "$(make print_ldflags)" -run TestDockerCommandBuildCancel -v ./executors/docker/...

GoLandでは

現在のところ、GoLandは動的なGoツール引数をサポートしていませんので、まずmake print_ldflags 、それを設定に貼り付ける必要があります。

note
デバッガを使用するには、最後の2つのフラグ (-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が必要な場合、無料で使えるものがいくつかあります：

ビルド依存関係の管理

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 用の開発者

Vagrant 内で複数のマシンを使用するため、Windows Server 2019 や Windows 10 インスタンスを実行するためのVagrantfileを提供します。

以下が必要です：

  • Vagrantのインストール。
  • Virtualboxインストール。
  • ハードディスクに30GB程度の空き容量があること。

どの仮想マシンを使用するかは、使用するケースによって異なります：

  • Windows ServerマシンにはDockerがプリインストールされており、GitLab Runner for Windowsで開発する場合は常に使用する必要があります。
  • Windows 10マシンはWindows環境をGUIで利用するためのもので、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 経由で接続します。 はローカルにインストールされた RDP プログラムを使用してマシンに接続します。

どちらのマシンでも、GitLab Runnerのソースコードは双方向で同期されるので、マシンからお気に入りのエディタで編集することができます。ソースコードは$GOROOT 環境変数の下にあります。私たちはRUNNER_SRC 環境変数を用意しており、PowerShell を使うときにcd $Env:RUNNER_SRC を使ってフルパスを調べることができます。

その他のリソース

  1. GitLab Runner マージリクエストのレビュー
  2. 新しい Windows バージョンのサポート追加
  3. Runner グループ - チームリソース