如何在ubuntu上使用gitlab ci

在 Ubuntu 上使用 GitLab CI 的完整上手指南

一 核心概念与准备

1. GitLab CI 是 GitLab 内置的持续集成/交付能力，代码推送后会触发流水线；真正执行任务的是 GitLab Runner。Runner 需要先在 Ubuntu 上安装并注册到你的项目或实例，随后按仓库根目录的 .gitlab-ci.yml 执行作业。Runner 支持多种 Executor（如 shell、docker、docker-ssh 等），选择 docker 可实现环境隔离与可重复性。

二 在 Ubuntu 安装并注册 GitLab Runner

1. 安装 Runner（Ubuntu 20.04/22.04/24.04 通用）
   1. 添加仓库并安装：
      1. curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
      2. sudo apt-get install -y gitlab-runner
   2. 验证服务：
      1. sudo gitlab-runner status
2. 注册 Runner（获取项目或实例的 URL 与 Registration token）
   1. 项目级：进入项目 Settings > CI/CD > Runners 复制；实例级：进入 Admin Area > Runners。
   2. 交互注册示例（按提示填写 URL、token、描述、标签；Executor 选 shell 或 docker）：
      1. sudo gitlab-runner register
   3. 注册完成后在 UI 中可见，并可在 /etc/gitlab-runner/config.toml 查看配置。

三 编写第一个 .gitlab-ci.yml 并触发流水线

1. 在项目根目录创建 .gitlab-ci.yml（示例为 Node.js 构建与测试；文件名为 .gitlab-ci.yml，注意不是 .yaml）：
   1. stages:
      1. build
      2. test
   2. cache:
      1. paths:
         1. node_modules/
   3. build-job:
      1. stage: build
      2. image: node:18
      3. script:
         1. npm ci --quiet
      4. artifacts:
         1. paths:
            1. node_modules/
   4. test-job:
      1. stage: test
      2. image: node:18
      3. script:
         1. npm test – --ci
2. 提交并推送：
   1. git add .gitlab-ci.yml
   2. git commit -m “Add CI pipeline”
   3. git push
3. 在 GitLab 项目 CI/CD > Pipelines 查看运行结果与日志；可用 CI Lint 校验语法（路径：项目 CI/CD 页面中的 Lint 工具）。

四 常见场景示例

1. 使用 Docker 构建镜像并推送到 GitLab 容器注册表（需在项目设置中启用 Container Registry）
   1. stages:
      1. build
      2. push
   2. variables:
      1. IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
   3. build:
      1. stage: build
      2. image: docker:24.0
      3. services:
         1. docker:24.0-dind
      4. variables:
         1. DOCKER_TLS_CERTDIR: “/certs”
      5. script:
         1. docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
         2. docker build -t $IMAGE .
   4. push:
      1. stage: push
      2. image: docker:24.0
      3. services:
         1. docker:24.0-dind
      4. variables:
         1. DOCKER_TLS_CERTDIR: “/certs”
      5. script:
         1. docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
         2. docker push $IMAGE
      6. only:
         1. main
2. 通过 SSH 部署到目标服务器（更安全做法：使用项目 Runner 直连目标机，避免把私钥交给共享 Runner）
   1. 在目标机创建部署用户并生成密钥（如用户 deployer），将公钥加入 ~/.ssh/authorized_keys。
   2. 在 GitLab 项目 Settings > CI/CD > Variables 添加：
      1. ID_RSA（类型：文件，值为私钥内容，勾选“受保护”）
      2. SERVER_IP（类型：变量，值为目标机 IP，勾选“受保护”与“掩码”）
      3. SERVER_USER（类型：变量，值为 deployer，勾选“受保护”与“掩码”）
   3. .gitlab-ci.yml 片段：
      1. deploy:
         1. stage: deploy
         2. image: alpine:latest
         3. before_script:
            1. apk add --no-cache openssh
            2. mkdir -p ~/.ssh
            3. chmod 700 ~/.ssh
            4. cp $ID_RSA ~/.ssh/id_rsa
            5. chmod 600 ~/.ssh/id_rsa
            6. ssh-keyscan $SERVER_IP >> ~/.ssh/known_hosts
         4. script:
            1. ssh $SERVER_USER@$SERVER_IP “cd /opt/app && git pull && docker compose up -d --build”
         5. only:
            1. main
         6. tags:
            1. your-runner-tag

五 排错与最佳实践

1. 作业无可用 Runner：到 Settings > CI/CD > Runners 检查 Runner 是否在线、是否被暂停，以及作业是否声明了正确的 tags；必要时为项目专属 Runner 设置标签并在作业中匹配。
2. Runner 服务与权限：使用专用系统用户运行 Runner，避免与业务用户混用；如需 Docker 执行器，确保 Runner 主机已安装 Docker 并合理配置 /etc/gitlab-runner/config.toml（如并发、缓存、超时等）。
3. 安全性：私钥等敏感信息放入 CI/CD Variables（文件类型用于私钥），尽量使用 受保护 与 掩码；避免使用共享 Runner 执行涉及生产部署的作业；SSH 免密登录仅授予必要权限，并限制目标机 sudo 使用范围。