# 访问GitLab Runner下载页面
# https://gitlab.com/gitlab-org/gitlab-runner/-/releases

# 下载GitLab Runner 17.0.0 Linux amd64
$ wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/v17.0.0/binaries/gitlab-runner-linux-amd64

# 添加执行权限
$ chmod +x /usr/local/bin/gitlab-runner

# 验证安装
$ gitlab-runner –version

输出示例如下：
Version: 17.0.0
Git revision: abc123d
Git branch: 17-0-stable
GO version: go1.22.0
Built: 2026-03-15T10:00:00+0000
OS/Arch: linux/amd64

# 查看帮助信息
$ gitlab-runner –help

输出示例如下：
NAME:
gitlab-runner – a GitLab Runner

USAGE:
gitlab-runner [global options] command [command options] [arguments…]

VERSION:
17.0.0 (abc123d)

AUTHOR:
GitLab Inc.

COMMANDS:
run run multi runner service
register register a new runner
unregister unregister specific runner
list List all configured runners
verify verify all registered runners
artifacts-download download and extract build artifacts (internal)
artifacts-upload create and upload build artifacts (internal)
cache-cleaner clean up old cache entries (internal)
cache-extractor extract cache contents (internal)
cache-archiver create and upload cache artifacts (internal)
health-check check health of the runner
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
–help, -h show help

方式二：系统包管理器安装

# CentOS/RHEL/Rocky Linux安装
$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
$ sudo yum install -y gitlab-runner

输出示例如下：
Dependencies resolved.
================================================================================
Package Architecture Version Repository Size
================================================================================
Installing:
gitlab-runner x86_64 17.0.0-1 gitlab-runner 50 M

Transaction Summary
================================================================================
Install 1 Package

Total download size: 50 M
Installed size: 100 M
Downloading Packages:
gitlab-runner-17.0.0-1.x86_64.rpm 10 MB/s | 50 MB 00:05
——————————————————————————–
Total 10 MB/s | 50 MB 00:05
Running transaction check
Transaction check succeeded.
Running transaction test
Transaction test succeeded.
Running transaction
Preparing : 1/1
Running scriptlet: gitlab-runner-17.0.0-1.x86_64 1/1
Installing : gitlab-runner-17.0.0-1.x86_64 1/1
Running scriptlet: gitlab-runner-17.0.0-1.x86_64 1/1
Verifying : gitlab-runner-17.0.0-1.x86_64 1/1

Installed:
gitlab-runner-17.0.0-1.x86_64

Complete!

# Ubuntu/Debian安装
$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
$ sudo apt-get install -y gitlab-runner

# 查看安装版本
$ gitlab-runner –version

输出示例如下：
Version: 17.0.0
Git revision: abc123d
Git branch: 17-0-stable
GO version: go1.22.0
Built: 2026-03-15T10:00:00+0000
OS/Arch: linux/amd64

方式三：Docker镜像下载

# 拉取GitLab Runner Docker镜像
$ docker pull gitlab/gitlab-runner:v17.0.0

输出示例如下：
v17.0.0: Pulling from gitlab/gitlab-runner
abc123d: Pull complete
def456g: Pull complete
…
Digest: sha256:abc123def456789012345678901234567890123456789012345678901234
Status: Downloaded newer image for gitlab/gitlab-runner:v17.0.0
docker.io/gitlab/gitlab-runner:v17.0.0

# 拉取最新版本
$ docker pull gitlab/gitlab-runner:latest

# 查看本地镜像
$ docker images | grep gitlab-runner

输出示例如下：
gitlab/gitlab-runner v17.0.0 abc123def456 2 days ago 800MB
gitlab/gitlab-runner latest abc123def456 2 days ago 800MB

方式四：Helm Chart部署

# 添加GitLab Helm仓库
$ helm repo add gitlab https://charts.gitlab.io

输出示例如下：
“gitlab” has been added to your repositories

# 更新仓库
$ helm repo update

输出示例如下：
Hang tight while we grab the latest from your chart repositories…
…Successfully got an update from the “gitlab” chart repository
Update Complete. ⎈Happy Helming⎈

# 搜索GitLab Runner Charts
$ helm search repo gitlab/gitlab-runner

输出示例如下：
NAME CHART VERSION APP VERSION DESCRIPTION
gitlab/gitlab-runner 0.65.0 17.0.0 GitLab Runner

# 下载Chart
$ helm pull gitlab/gitlab-runner –version 0.65.0

# 解压Chart
$ tar -xzf gitlab-runner-0.65.0.tgz

# 查看Chart内容
$ ls gitlab-runner/

输出示例如下：
Chart.yaml LICENSE README.md templates values.yaml

# 创建gitlab-runner用户
$ sudo useradd –comment ‘GitLab Runner’ –create-home gitlab-runner –shell /bin/bash

# 安装为系统服务
$ sudo gitlab-runner install –user=gitlab-runner –working-directory=/home/gitlab-runner

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0

# 启动服务
$ sudo gitlab-runner start

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0
Service started successfully.

# 查看服务状态
$ sudo gitlab-runner status

输出示例如下：
Service is running

# 或使用systemctl管理
$ sudo systemctl enable gitlab-runner
$ sudo systemctl start gitlab-runner
$ sudo systemctl status gitlab-runner

输出示例如下：
● gitlab-runner.service – GitLab Runner
Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; preset: disabled)
Active: active (running) since Fri 2026-03-15 10:00:00 CST; 10s ago
Main PID: 12345 (gitlab-runner)
Tasks: 15
Memory: 45.2M
CPU: 1.2s
CGroup: /system.slice/gitlab-runner.service
└─12345 /usr/bin/gitlab-runner run –working-directory /home/gitlab-runner –config /etc/gitlab-runner/config.toml –service gitlab-runner –user gitlab-runner

Mar 15 10:00:00 fgedu.net.cn systemd[1]: Started GitLab Runner.
Mar 15 10:00:00 fgedu.net.cn gitlab-runner[12345]: Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0

步骤2：Docker方式部署Runner

# 创建配置目录
$ mkdir -p /data/gitlab-runner/config

# 启动GitLab Runner容器
$ docker run -d \
–name gitlab-runner \
–restart always \
-v /data/gitlab-runner/config:/etc/gitlab-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
gitlab/gitlab-runner:v17.0.0

输出示例如下：
abc123def456789012345678901234567890123456789012345678901234

# 查看容器状态
$ docker ps | grep gitlab-runner

输出示例如下：
abc123def456 gitlab/gitlab-runner:v17.0.0 “/usr/bin/dumb-init …” 10 seconds ago Up 9 seconds gitlab-runner

# 查看日志
$ docker logs gitlab-runner

输出示例如下：
Runtime platform arch=amd64 os=linux pid=1 revision=abc123d version=17.0.0
Starting multi-runner from /etc/gitlab-runner/config.toml… builds=0 max_builds=0
Running in system-mode.
Configuration loaded builds=0 max_builds=0
listen_address not defined, metrics & health endpoints disabled builds=0 max_builds=0

# 访问GitLab项目设置页面获取Token
# 项目级别：Settings -> CI/CD -> Runners -> New project runner
# 组级别：Settings -> CI/CD -> Runners -> New group runner
# 实例级别：Admin Area -> CI/CD -> Runners -> New instance runner

# 注册Token示例：glrt-abc123def456789012345678901234

# GitLab服务器地址
# http://gitlab.fgedu.net.cn 或 https://gitlab.fgedu.net.cn

步骤2：注册Runner

# 交互式注册
$ sudo gitlab-runner register

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0
Running in system-mode.

Enter the GitLab instance URL (for example, https://gitlab.com/):
http://gitlab.fgedu.net.cn

Enter the registration token:
glrt-abc123def456789012345678901234

Enter a description for the runner:
[fgedu.net.cn]: fgedu-runner-01

Enter tags for the runner (comma-separated):
docker,build,deploy

Enter optional maintenance note for the runner:
Production build runner

WARNING: Support for registration tokens and runner parameters in the ‘register’ command has been deprecated in GitLab Runner 15.6 and will be replaced with support for authentication tokens. For more information, see https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html

Registering runner… succeeded runner=abc123d
Enter an executor: custom, docker, docker-ssh, instance, kubernetes, parallels, shell, ssh, virtualbox, docker+machine, docker-ssh+machine:
docker

Enter the default Docker image (for example ruby:2.7):
maven:3.9.6-eclipse-temurin-17

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”

# 非交互式注册
$ sudo gitlab-runner register \
–non-interactive \
–url http://gitlab.fgedu.net.cn \
–token glrt-abc123def456789012345678901234 \
–description “fgedu-runner-01” \
–tag-list “docker,build,deploy” \
–executor docker \
–docker-image maven:3.9.6-eclipse-temurin-17

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0
Running in system-mode.
Registering runner… succeeded runner=abc123d
Runner registered successfully. Feel free to start it, but if it’s running already the config should be automatically reloaded!

步骤3：验证注册

# 查看已注册的Runner
$ sudo gitlab-runner list

输出示例如下：
Listing configured runners ConfigFile=/etc/gitlab-runner/config.toml
fgedu-runner-01 Executor=docker Token=abc123d URL=http://gitlab.fgedu.net.cn

# 验证Runner连接
$ sudo gitlab-runner verify

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0
Running in system-mode.
Verifying runner… is alive runner=abc123d

# 查看配置文件
$ cat /etc/gitlab-runner/config.toml

输出示例如下：
concurrent = 4
check_interval = 0
shutdown_timeout = 0

[session_server]
session_timeout = 1800

[[runners]]
name = “fgedu-runner-01”
url = “http://gitlab.fgedu.net.cn”
id = 123
token = “abc123d”
token_obtained_at = 2026-03-15T10:00:00Z
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 = “maven:3.9.6-eclipse-temurin-17”
privileged = false
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = [“/cache”]
shm_size = 0

# 创建.gitlab-ci.yml文件
$ cat > .gitlab-ci.yml << 'EOF' stages: - build - test - docker - deploy variables: MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository" DOCKER_REGISTRY: "192.168.1.51:5000" IMAGE_NAME: "${DOCKER_REGISTRY}/fgedu-app" IMAGE_TAG: "${CI_COMMIT_SHORT_SHA}" cache: paths: - .m2/repository/ build: stage: build image: maven:3.9.6-eclipse-temurin-17 script: - echo "Building application..." - mvn clean package -DskipTests artifacts: paths: - target/*.jar expire_in: 1 hour test: stage: test image: maven:3.9.6-eclipse-temurin-17 script: - echo "Running tests..." - mvn test artifacts: reports: junit: - target/surefire-reports/TEST-*.xml expire_in: 1 week docker-build: stage: docker image: docker:latest services: - docker:dind script: - echo "Building Docker image..." - docker login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${DOCKER_REGISTRY} - docker build -t ${IMAGE_NAME}:${IMAGE_TAG} . - docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:latest - docker push ${IMAGE_NAME}:${IMAGE_TAG} - docker push ${IMAGE_NAME}:latest only: - main deploy: stage: deploy image: bitnami/kubectl:latest script: - echo "Deploying to Kubernetes..." - kubectl config set-cluster kubernetes --server="${KUBE_URL}" --insecure-skip-tls-verify=true - kubectl config set-credentials gitlab --token="${KUBE_TOKEN}" - kubectl config set-context default --cluster=kubernetes --user=gitlab - kubectl config use-context default - kubectl set image deployment/fgedu-app fgedu-app=${IMAGE_NAME}:${IMAGE_TAG} -n default only: - main when: manual EOF # 提交到Git仓库 $ git add .gitlab-ci.yml $ git commit -m "Add GitLab CI Pipeline" $ git push origin main

步骤2：查看Pipeline执行

# 访问GitLab项目页面
# CI/CD -> Pipelines

# Pipeline执行日志示例：
Running with gitlab-runner 17.0.0 (abc123d)
on fgedu-runner-01 abc123d
Preparing the “docker” executor
Using Docker executor with image maven:3.9.6-eclipse-temurin-17 …
Pulling docker image maven:3.9.6-eclipse-temurin-17 …
Using docker image sha256:abc123d for maven:3.9.6-eclipse-temurin-17 with digest maven@sha256:def456…
Preparing environment
Running on runner-abc123d-project-123-concurrent-0 via fgedu.net.cn…
Getting source from Git repository
Fetching changes with git depth set to 50…
Reinitialized existing Git repository in /builds/fgedu/fgedu-app/.git/
Checking out abc123d as detached HEAD (ref is main)…

Removing .m2/repository/
Skipping Git submodules setup
Executing “step_script” stage of the job script
Using docker image sha256:abc123d for maven:3.9.6-eclipse-temurin-17 with digest maven@sha256:def456…
$ echo “Building application…”
Building application…
$ mvn clean package -DskipTests
[INFO] Scanning for projects…
[INFO]
[INFO] ———————-< com.fgedu:fgedu-app >———————-
[INFO] Building fgedu-app 1.0.0
[INFO] ——————————–[ jar ]———————————
[INFO]
[INFO] — maven-clean-plugin:2.5:clean (default-clean) @ fgedu-app —
[INFO] Deleting /builds/fgedu/fgedu-app/target
[INFO]
[INFO] — maven-resources-plugin:2.6:resources (default-resources) @ fgedu-app —
[INFO] Copying 2 resources
[INFO]
[INFO] — maven-compiler-plugin:3.1:compile (default-compile) @ fgedu-app —
[INFO] Changes detected – recompiling the module!
[INFO] Compiling 10 source files
[INFO]
[INFO] — maven-resources-plugin:2.6:testResources (default-testResources) @ fgedu-app —
[INFO] Copying 1 resource
[INFO]
[INFO] — maven-surefire-plugin:2.12:test (default-test) @ fgedu-app —
[INFO] Tests are skipped.
[INFO]
[INFO] — maven-jar-plugin:2.4:jar (default-jar) @ fgedu-app —
[INFO] Building jar: /builds/fgedu/fgedu-app/target/fgedu-app-1.0.0.jar
[INFO] ————————————————————————
[INFO] BUILD SUCCESS
[INFO] ————————————————————————
[INFO] Total time: 10.123 s
[INFO] Finished at: 2026-03-15T10:00:00+08:00
[INFO] ————————————————————————
Saving cache for successful job
Creating cache fgedu-app-cache…
.m2/repository/: found 123 matching files
Uploading cache.zip to http://gitlab.fgedu.net.cn/api/v4/jobs/12345/cache …
Created cache
Uploading artifacts for successful job
Uploading artifacts…
target/*.jar: found 1 matching files and directories
Uploading artifacts as “archive” to coordinator… ok id=12345 responseStatus=201 Created token=abc123d
Cleaning up project directory and file based variables
Job succeeded

# Shell执行器：在Runner主机上直接执行命令
# 优点：配置简单，无需额外依赖
# 缺点：环境隔离性差，可能影响主机环境

# Docker执行器：在Docker容器中执行命令
# 优点：环境隔离，可自定义镜像
# 缺点：需要Docker环境，资源开销较大

# Kubernetes执行器：在Kubernetes Pod中执行命令
# 优点：弹性伸缩，资源利用率高
# 缺点：配置复杂，需要Kubernetes集群

# SSH执行器：通过SSH远程执行命令
# 优点：可利用远程服务器资源
# 缺点：网络延迟，需要配置SSH密钥

# VirtualBox/Parallels执行器：在虚拟机中执行命令
# 优点：完全隔离的环境
# 缺点：资源开销大，启动慢

# 编辑Runner配置文件
$ sudo vi /etc/gitlab-runner/config.toml

[[runners]]
name = “fgedu-docker-runner”
url = “http://gitlab.fgedu.net.cn”
token = “abc123d”
executor = “docker”
[runners.docker]
tls_verify = false
image = “maven:3.9.6-eclipse-temurin-17”
privileged = true
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = [“/cache”, “/var/run/docker.sock:/var/run/docker.sock”]
shm_size = 256m
pull_policy = [“if-not-present”]
allowed_images = [“maven:*”, “docker:*”, “node:*”, “python:*”]
allowed_services = [“docker:dind”, “postgres:*”, “mysql:*”]
[runners.cache]
Type = “s3”
Path = “runner-cache”
Shared = false
[runners.cache.s3]
ServerAddress = “minio.fgedu.net.cn”
BucketName = “gitlab-runner-cache”
AccessKey = “minioadmin”
SecretKey = “minioadmin”
Insecure = true

# 重启Runner使配置生效
$ sudo gitlab-runner restart

输出示例如下：
Runtime platform arch=amd64 os=linux pid=12345 revision=abc123d version=17.0.0
Service restarted successfully.

步骤2：配置Docker镜像拉取

# 配置私有镜像仓库认证
$ sudo mkdir -p /etc/gitlab-runner/certs.d/192.168.1.51:5000
$ echo ‘{“insecure-registries”: [“192.168.1.51:5000”]}’ | sudo tee /etc/docker/daemon.json
$ sudo systemctl restart docker

# 在.gitlab-ci.yml中使用私有镜像
image: 192.168.1.51:5000/custom-maven:latest

# 配置镜像拉取策略
# pull_policy = [“if-not-present”] # 优先使用本地镜像
# pull_policy = [“always”] # 始终拉取最新镜像
# pull_policy = [“never”] # 只使用本地镜像

# 创建values.yaml配置文件
$ cat > values.yaml << EOF gitlabUrl: http://gitlab.fgedu.net.cn runnerRegistrationToken: "glrt-abc123def456789012345678901234" rbac: create: true rules: - apiGroups: [""] resources: ["pods", "pods/exec", "secrets"] verbs: ["create", "delete", "get", "list", "patch", "update", "watch"] - apiGroups: [""] resources: ["pods/log"] verbs: ["get", "list"] runners: config: | [[runners]] [runners.kubernetes] namespace = "gitlab-runner" image = "maven:3.9.6-eclipse-temurin-17" privileged = true [[runners.kubernetes.volumes.pvc]] name = "maven-repo" mount_path = "/root/.m2" [[runners.kubernetes.volumes.config_map]] name = "docker-config" mount_path = "/root/.docker" tags: "kubernetes,build,deploy" runUntagged: false concurrent: 10 EOF # 部署Runner $ helm install gitlab-runner -n gitlab-runner --create-namespace gitlab/gitlab-runner -f values.yaml 输出示例如下： NAME: gitlab-runner LAST DEPLOYED: Fri Mar 15 10:00:00 2026 NAMESPACE: gitlab-runner STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: Your GitLab Runner should now be registered against the GitLab instance reachable at: "http://gitlab.fgedu.net.cn" # 查看部署状态 $ kubectl get pods -n gitlab-runner 输出示例如下： NAME READY STATUS RESTARTS AGE gitlab-runner-abc123d-def456 1/1 Running 0 1m # 查看日志 $ kubectl logs -f gitlab-runner-abc123d-def456 -n gitlab-runner 输出示例如下： Runtime platform arch=amd64 os=linux pid=1 revision=abc123d version=17.0.0 Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0 max_builds=10 Running in system-mode. Configuration loaded builds=0 max_builds=10 Registering runner... succeeded runner=abc123d Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

步骤2：配置Kubernetes执行器

# 在.gitlab-ci.yml中使用Kubernetes执行器
job:
stage: build
image: maven:3.9.6-eclipse-temurin-17
tags:
– kubernetes
variables:
KUBERNETES_CPU_REQUEST: “500m”
KUBERNETES_MEMORY_REQUEST: “512Mi”
KUBERNETES_CPU_LIMIT: “2000m”
KUBERNETES_MEMORY_LIMIT: “2Gi”
script:
– mvn clean package
artifacts:
paths:
– target/*.jar

# 使用自定义Pod配置
job:
stage: build
tags:
– kubernetes
image: maven:3.9.6-eclipse-temurin-17
services:
– name: postgres:15
alias: db
variables:
POSTGRES_DB: test
POSTGRES_USER: test
POSTGRES_PASSWORD: test
script:
– mvn clean package