如何在ubuntu上使用gitlab ci

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

一 核心概念与准备

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

二 在 Ubuntu 安装并注册 GitLab Runner

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

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

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

四 常见场景示例

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

五 排错与最佳实践

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