Ubuntu Linux 24.04 LTSにGitLab Runnerをインストールして、TerraformでGitLabに登録する

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 24.04.2 LTS
Release:        24.04
Codename:       noble


$ uname -srvmpio
Linux 6.8.0-56-generic #58-Ubuntu SMP PREEMPT_DYNAMIC Fri Feb 14 15:33:28 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

ここにGitLab Runnerをインストールします。

GitLab Runnerをインストールする環境には、Dockerもイントール済みとします。

$ docker version
Client: Docker Engine - Community
 Version:           28.0.4
 API version:       1.48
 Go version:        go1.23.7
 Git commit:        b8034c0
 Built:             Tue Mar 25 15:07:16 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          28.0.4
  API version:      1.48 (minimum version 1.24)
  Go version:       go1.23.7
  Git commit:       6430e49
  Built:            Tue Mar 25 15:07:16 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.26
  GitCommit:        753481ec61c7c8955a23d6ff7bc8e4daed455734
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

GitLab。こちらはすでに構築済みで、192.168.0.6で動作しているものとします。

$ sudo gitlab-rake gitlab:env:info

System information
System:         Ubuntu 24.04
Current User:   git
Using RVM:      no
Ruby Version:   3.2.5
Gem Version:    3.6.5
Bundler Version:2.6.5
Rake Version:   13.0.6
Redis Version:  7.0.15
Sidekiq Version:7.2.4
Go Version:     unknown

GitLab information
Version:        17.10.1
Revision:       5ef58a00091
Directory:      /opt/gitlab/embedded/service/gitlab-rails
DB Adapter:     PostgreSQL
DB Version:     14.17
URL:            http://192.168.0.6
HTTP Clone URL: http://192.168.0.6/some-group/some-project.git
SSH Clone URL:  git@192.168.0.6:some-group/some-project.git
Using LDAP:     no
Using Omniauth: yes
Omniauth Providers:

GitLab Shell
Version:        14.41.0
Repository storages:
- default:      unix:/var/opt/gitlab/gitaly/gitaly.socket
GitLab Shell path:              /opt/gitlab/embedded/service/gitlab-shell

Gitaly
- default Address:      unix:/var/opt/gitlab/gitaly/gitaly.socket
- default Version:      17.10.1
- default Git Version:  2.48.1.gl1

Terraform。

$ terraform version
Terraform v1.11.3
on linux_amd64

GitLab Runnerをインストールする

まずはこちらに従って、GitLab Runnerをインストールします。

Install GitLab Runner using the official GitLab repositories | GitLab Docs

GitLab Runner用のaptリポジトリーの追加とインストール。最新版のGitLab Runnerをインストールするために行うことは、
これだけです。

$ curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
$ sudo apt install gitlab-runner

インストールが完了すると、systemdのユニットとして登録、起動しています。

$ systemctl status gitlab-runner
● gitlab-runner.service - GitLab Runner
     Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; preset: enabled)
     Active: active (running) since Mon 2025-03-31 19:59:18 JST; 1min 9s ago
   Main PID: 1668 (gitlab-runner)
      Tasks: 8 (limit: 2317)
     Memory: 23.6M (peak: 24.1M)
        CPU: 136ms
     CGroup: /system.slice/gitlab-runner.service
             └─1668 /usr/bin/gitlab-runner run --config /etc/gitlab-runner/config.toml --working-directory /home/gitlab-runner --service gitlab-runner --user gitlab-runner

GitLab Runnerの管理方針を決める

インストールしたGitLab RunnerをGitLabに登録する前に、GitLab Runnerの管理方針を決める必要があります。

GitLab Runnerは、属するスコープによって3つの種類があります。

Instance runners
Group runners
Project runners

Manage runners | GitLab Docs

端的に言うと、GitLab Runnerの共有範囲です。たとえばInstance runnersであればGitLabインスタンス全体で共有される
GitLab Runnerになりますし、Project runnersであれば特定のプロジェクトのみで使われるGitLab Runnerになります。

今回はGroup runnersにすることにします。

Manage runners / Group runners

ということは、先にグループを作成する必要があります。

TerraformでGitLabリソースを作成する

Group runnersとして登録することにしたので、必要なリソースをTerraformで作成することにします。

ひとまず、グループ、プロジェクト、ユーザーまで作ることにしました。

terraform.tf

terraform {
  required_version = "1.11.3"

  required_providers {
    gitlab = {
      source  = "gitlabhq/gitlab"
      version = "17.10.0"
    }
  }
}

main.tf

variable "root_access_token" {
  type      = string
  ephemeral = true
}

provider "gitlab" {
  token    = var.root_access_token
  base_url = "http://192.168.0.6/"
}

resource "gitlab_group" "sample_group" {
  name = "sample group"
  path = "sample-group"
}

resource "gitlab_project" "sample_app" {
  name         = "sample-app"
  namespace_id = gitlab_group.sample_group.id
}

resource "gitlab_group_membership" "sample_user" {
  group_id     = gitlab_group.sample_group.id
  user_id      = gitlab_user.sample_user.id
  access_level = "owner"
}

resource "gitlab_user" "sample_user" {
  name     = "sample-user"
  username = "sample-user"
  password = "P@ssw0rd"
  email    = "sample-user@example.com"

  namespace_id = gitlab_group.sample_group.id
}

アクセストークンは環境変数で定義。

$ export TF_VAR_root_access_token=...

リソース作成。

$ terraform init
$ terraform apply

Runner作成ページを見てみる

リソースができたら、作成したユーザーでGitLabにログインします。所属しているグループを選び、Build → Runnersを
選びます。

「New group runner」というボタンを押すと、Runnerの登録ページに進みます。

GitLab Runnerが特定のタグを実行対象とするかを選べますが、今回はタグなし（Run untagged jobs）を選びます。

またdescriptionも入れておきます。

そして「Create runner」ボタンを押せばいいのですが…今回はこの内容をTerraformで行うことにします。

TerraformでRunnerを作成する

先ほどのTerraformの構成ファイル、main.tfに以下のリソース定義を追加します。

resource "gitlab_user_runner" "group_runner" {
  runner_type = "group_type"

  group_id = gitlab_group.sample_group.id

  description = "sample group runner"
  untagged    = true
}

output "runner_authentication_token" {
  value     = gitlab_user_runner.group_runner.token
  sensitive = true
}

gitlab_user_runner (Resource)

Runnerのスコープは、runner_typeで指定します。group_typeを指定したので、group_idの指定も必要になりますね。

  runner_type = "group_type"

  group_id = gitlab_group.sample_group.id

applyします。

$ terraform apply

実行結果のauthentication tokenはsensitive = trueなので見えないのですが

Outputs:

runner_authentication_token = <sensitive>

terraform outputで直接指定することで確認できます。

$ terraform output runner_authentication_token
"glrt-xxxxxxxxxx"

glrt-で始まるトークンが作られます。

GitLabのグループのRunnersを見ると、登録されていることが確認できます。

とはいえ、これだけだと実際のGitLab Runnerとの紐付けができていません。

GitLab Runnerを登録する

作成したauthentication tokenを使って、GitLab RunnerをGitLabに登録します。

Registering runners | GitLab Docs

ひとまず、ドキュメントに沿って（少し変えていますが）登録。RUNNER_TOKENには、先ほど作成したauthentication tokenを
指定しているものとします。

$ RUNNER_TOKEN=...
$ sudo gitlab-runner register \
  --non-interactive \
  --url "http://192.168.0.6/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image ubuntu:24.04 \
  --description "sample group runner"

無事登録できたようです。

Runtime platform                                    arch=amd64 os=linux pid=1838 revision=ef334dcc version=17.10.1
Running in system-mode.

Verifying runner... is valid                        runner=t2_zQYRsE
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

設定ファイルはこんな感じになっているので、必要に応じて変更します。

/etc/gitlab-runner/config.toml

concurrent = 1
check_interval = 0
connection_max_age = "15m0s"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "sample group runner"
  url = "http://192.168.0.6/"
  id = 1
  token = "glrt-xxxxxxxxxx"
  token_obtained_at = 2025-03-31T11:40:53Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "ubuntu:24.04"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
    network_mtu = 0

GitLab Runnerは、config.tomlの変更有無を3秒毎に確認しているようです。またSIGHUPシグナルを送ることでもリロード
できるようですね。

GitLab Runner checks for configuration modifications every 3 seconds and reloads if necessary. GitLab Runner also reloads the configuration in response to the SIGHUP signal.

Advanced configuration | GitLab Docs

グループ上のRunnerも「Online」になりました。

ここで、説明を飛ばした以下の部分を見ていきます。

  --executor "docker" \
  --docker-image ubuntu:24.04 \

--executorというのはExecutorの指定で、Executorというのはどのような環境でCI／CDパイプラインを実行するかを
指定するものです。シェル、VirtualBox、Docker、Kubernetesなどの選択肢があります。

Executors | GitLab Docs

今回選んだのはDocker Executorです。

Docker executor | GitLab Docs

ここで指定している--docker-imageはなんなのか？というところなのですが、説明を見るとCI／CDパイプラインを
実行する時に使うDockerイメージになるようです。

The name of the Docker image that the runner uses to run jobs.

Docker executor / Configure images and services

CI／CDパイプラインの中に含まれる各ジョブで使用するイメージは.gitlab-ci.yml内でそれぞれ指定するのですが、
指定せずscriptを書いた場合に利用されるイメージなのかもしれません。

今回用意した後述の.gitlab-ci.ymlにはすべてのジョブにimageを指定したからか、--docker-imageで指定したイメージが
使われることはありませんでした。

登録したRunnerを使ってCI／CDパイプラインを実行してみる

最後に、登録したRunnerを使ってCI／CDパイプラインを実行してみましょう。

ドキュメントとしてはこちらですね。

Use CI/CD to build your application | GitLab Docs

テストコードのみのApache Mavenプロジェクトを作成することにします。

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.littlewings</groupId>
    <artifactId>sample-app</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.12.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

src/test/java/org/littlewings/gitlab/GitLabRunnerTest.java

package org.littlewings.gitlab;

import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

class GitLabRunnerTest {
    @Test
    void test() {
        Assertions.assertEquals(5, 2 + 3);
    }
}

.gitlab-ci.ymlは、こんな感じで用意。

.gitlab-ci.yml

build-job:
  stage: build
  image: maven:3.9.9-eclipse-temurin-21
  script:
    - mvn compile

test-job:
  stage: test
  image: maven:3.9.9-eclipse-temurin-21
  script:
    - mvn test

今回は.gitlab-ci.ymlの内容を詳しく見ません。必要に応じてリファレンスや

CI/CD YAML syntax reference | GitLab Docs

CI／CDのガイドを見ていきましょう。

Use CI/CD to build your application | GitLab Docs

git initして、ファイルを登録してpush。

$ git init --initial-branch=main
$ git remote add origin http://192.168.0.6/sample-group/sample-app.git
$ git add pom.xml .gitlab-ci.yml src
$ git config --local user.name "sample-user"
$ git config --local user.email "sample-user@example.com"
$ git commit -m 'initial commit'
$ git push --set-upstream origin main

特になにも設定していないので、pushされた変更に反応してCI／CIパイプラインが動き出します。