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）。

Ubuntu GitLab的CI/CD如何配置

最新问答

相关标签