Ubuntu GitLab的CI/CD如何配置

Ubuntu 上 GitLab CI/CD 配置全流程

一 准备与安装

• 安装 GitLab Runner（Ubuntu 20.04/22.04 示例）
  • 更新索引并安装依赖

    sudo apt-get update
    sudo apt-get install -y curl ca-certificates
    

  • 添加 Runner 仓库并安装

    curl -L --output /usr/share/keyrings/gitlab-runner-archive-keyring.gpg \
      https://packages.gitlab.com/gitlab/gitlab-runner/gpgkey
    echo "deb [signed-by=/usr/share/keyrings/gitlab-runner-archive-keyring.gpg] \
      https://packages.gitlab.com/gitlab/gitlab-runner/ubuntu $(lsb_release -cs) main" \
      | sudo tee /etc/apt/sources.list.d/gitlab-runner.list >
         /dev/null
    sudo apt-get update
    sudo apt-get install -y gitlab-runner
    

• 如自建 GitLab，请先安装 GitLab（可选，使用 SaaS 可跳过）

  sudo apt-get update
  sudo apt-get install -y curl openssh-server ca-certificates tzdata perl
  curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  sudo EXTERNAL_URL="http://your-gitlab-domain-or-ip" apt-get install -y gitlab-ce
  

  安装完成后通过浏览器访问 EXTERNAL_URL 完成初始化。

二 注册 Runner

• 获取注册信息
  • 项目级：进入项目 → Settings → CI/CD → Runners → 展开 New project runner，复制 URL 与 registration token。
  • 实例级：进入 Admin Area → Runners 获取。
• 注册 Runner（交互式）

  sudo gitlab-runner register
  # 依次输入：GitLab 实例 URL、注册 Token
  # 输入 Runner 描述（如：ubuntu-shell-runner）
  # 输入标签（如：ci,deploy；后续作业可用 tags 指定）
  # 选择执行器：Shell（简单）或 Docker（推荐隔离环境）
  # 如选 Docker，可指定默认镜像（如：alpine:latest）
  

• 常用注册参数（非交互）

  sudo gitlab-runner register \
    --url https://gitlab.com/ \
    --registration-token PROJECT_TOKEN \
    --executor docker \
    --description "ubuntu-docker-runner" \
    --tag-list "ci,docker" \
    --docker-image "alpine:latest" \
    --run-untagged=false \
    --locked=false
  

• 常用命令

  sudo gitlab-runner list          # 查看已注册 Runner
  sudo gitlab-runner verify        # 校验配置
  sudo gitlab-runner restart       # 重启服务
  

  注册完成后，Runner 会在 Pipelines 页面自动接单执行作业。

三 编写 .gitlab-ci.yml

• 最小可用示例（Node.js）

  stages:
    - build
    - test
    - deploy
  
  variables:
    NODE_VERSION: "18"
  
  build_job:
    stage: build
    image: node:$NODE_VERSION
    script:
      - npm ci
      - npm run build --if-present
    artifacts:
      paths:
        - dist/
      expire_in: 1 hour
  
  test_job:
    stage: test
    image: node:$NODE_VERSION
    script:
      - npm test -- --ci
    dependencies:
      - build_job
  
  deploy_job:
    stage: deploy
    image: alpine:latest
    before_script:
      - apk add --no-cache openssh-client rsync
      - mkdir -p ~/.ssh
      - echo "$SSH_PRIVATE_KEY" | tr -d '\r' >
       ~/.ssh/id_rsa
      - chmod 600 ~/.ssh/id_rsa
      - ssh-keyscan -H $DEPLOY_HOST >
      >
       ~/.ssh/known_hosts
    script:
      - rsync -avz --delete dist/ $DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH
    environment:
      name: production
      url: https://$DEPLOY_HOST
    only:
      - main
  

• 关键要点
  • stages 定义阶段顺序；jobs 定义具体任务；image 指定运行环境。
  • artifacts 用于在阶段间传递产物（如上例把 dist/ 传给部署）。
  • dependencies 显式声明依赖，减少不必要下载。
  • environment 标记部署环境，便于回滚与审查。

四 配置变量与权限

• 添加 CI/CD 变量
  • 项目 → Settings → CI/CD → Variables → 新建变量：
    • SSH_PRIVATE_KEY：部署用私钥（建议 Masked，非 Protected 除非仅 main 分支可用）
    • DEPLOY_USER / DEPLOY_HOST / DEPLOY_PATH：目标主机与路径
    • 如需推送到 GitLab 容器镜像库，添加 CI_REGISTRY_USER / CI_REGISTRY_PASSWORD
• 安全建议
  • 尽量使用 Masked 与 Protected 标记敏感变量；仅对受保护分支/标签启用。
  • 使用 only/except 或 rules 精确控制作业触发分支。
  • Runner 选择 Docker 执行器可获得更好的隔离；如用 Shell，请确保 gitlab-runner 用户具备必要权限。

五 运行与排错

• 触发与查看
  • 推送代码到目标分支（如 main）将自动触发 Pipeline。
  • 进入项目 → CI/CD → Pipelines 查看运行状态、作业日志与产物；失败作业可点进 Job 查看完整输出定位问题。
• 常见问题速查
  • 作业未运行：检查 Runner 是否在线、tags 是否匹配、项目是否允许该 Runner 执行（run_untagged 设置）。
  • SSH 部署失败：确认 SSH_PRIVATE_KEY 正确、known_hosts 已添加、DEPLOY_USER 有目标路径写权限。
  • Docker 构建/推送失败：确认 CI_REGISTRY 认证变量正确，镜像名与标签符合规范（如使用 $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA）。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！