HelloWorld

HelloWorld GitLab 集成教程

作者：

user

在

本教程以实操角度带你把一个 HelloWorld 项目完整接入 GitLab：先建仓库并推送代码，再配置 .gitlab-ci.yml 实现持续集成（编译、测试、打包），接着注册 Runner 执行任务，最后配置变量、制品和自动部署到远端或 GitLab Pages。每一步配有命令示例、常见错误排查与安全建议，目的是让你能在一小时内把本地项目变成可自动化构建与发布的流水线，同时理解背后的原理便于后续扩展。

HelloWorld GitLab 集成教程

为什么要把 HelloWorld 接入 GitLab？先讲清楚原理

把 HelloWorld 接入 GitLab，不只是把代码放到远程仓库，而是把“自动化”这一能力加到开发流程中。想象你做饭，仓库是食材冰箱，CI/CD 是厨房流程：有了标准流程，每次做饭都会按步骤来，不会忘了调料，也能把饭更快端上桌。GitLab 提供代码托管、分支管理、合并请求、CI/CD、镜像仓库等功能，连在一起可以把开发、测试和部署串成一条自动化的生产线。

准备工作（先把基础打好）

必备项

  • 一个 GitLab 账号和可用的项目权限（自建 GitLab 或 gitlab.com）。
  • 本地 Git 环境（git 命令行）。
  • 一台可以运行 Runner 的机器（本地或云），或使用共享 Runner。
  • 若需部署：目标服务器的 SSH 权限或 GitLab Pages 静态托管权限。

建议准备

  • 将敏感配置放在 GitLab CI/CD 变量（Variables）里，不要写在代码里。
  • 使用容器化（Docker）可以让 CI 环境更可控。

第一步：创建仓库并推送 HelloWorld

这里以一个最简单的 Node.js HelloWorld 为例，目录结构清晰，方便在 CI 里运行测试与构建。

  • 在 GitLab 上新建项目（Private 或 Public，根据需要）。
  • 本地初始化并推送：

示例命令

git init
git remote add origin [email protected]:yourname/helloworld.git
echo 'console.log("Hello World");' > index.js
git add .
git commit -m "initial HelloWorld"
git push -u origin master

第二步：理解 .gitlab-ci.yml 的基本结构

.gitlab-ci.yml 是 GitLab CI 的配置文件，放在仓库根目录。文件通过 stages 定义阶段（比如 build、test、deploy），通过 job 定义任务，job 决定在哪个阶段运行、使用哪个镜像、执行哪些脚本、何时产出制品（artifacts）或触发部署。

关键概念一览

  • stages：流水线阶段顺序执行（也可以并行多个 job）。
  • job：阶段中的具体任务，有 script、tags、artifacts、only/except 等配置。
  • runner：执行 job 的实际工作者，可以是 Shell、Docker、Kubernetes 等。
  • artifacts：任务产物，可以在后续 job 下载或保存为构建制品。
  • variables：CI 内使用的环境变量，支持在项目设置里定义保护变量。

第三步：示范 .gitlab-ci.yml（最小可运行）

下面给出一个简单且常用的 Node.js 示例，完成安装、测试和打包（如果有）并保存构建产物。

stages:
  - install
  - test
  - package

install:
image: node:16
stage: install
script:
- npm ci
artifacts:
paths:
- node_modules/


test:
image: node:16
stage: test
script:
- npm test


package:
image: node:16
stage: package
script:
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 week

逐行解释（用费曼法来讲明白）

  • stages 定义了三个阶段：install → test → package，类似做饭的流程：先备料（install），再检验口味（test），最后装盘（package）。
  • 每个 job 都用了官方 Node 镜像，保证运行环境一致。
  • install 的 artifacts 把 node_modules 缓存在后续阶段，减少重复安装时间。
  • package 用 expire_in 控制构建制品的保存时间，避免无限占用空间。

第四步：Runner 的选择与注册

Runner 决定你的 job 在哪儿、用什么方式执行。有这几种常见 Runner：

  • Shared Runner（GitLab 提供，适合小项目或试用）。
  • Specific Runner（你自己注册在某台机器上，适合有特殊依赖或需要私有网络访问）。
  • Docker/Kubernetes Runner（容器化执行，隔离性好）。

如何在本地注册一个 Shell Runner（简化版）

  • 在目标机器上安装 gitlab-runner（按照操作系统用官方文档执行）。
  • 运行注册命令并填写信息：
sudo gitlab-runner register
# 填写 gitlab URL、registration token、描述、tags、executor（shell 或 docker）等

注册后，回到项目页面可以看到 Runner 已被关联，然后就可以执行 pipeline。

第五步：管理变量与密钥（不要把秘密写在代码里）

把敏感信息（比如 API Key、SSH 私钥、Docker registry 凭据）放到 GitLab 项目的 Settings → CI/CD → Variables。变量可以标记为 protected（仅在受保护分支/标签上可用）或 masked（在 job 日志中隐藏）。

变量名 用途
SSH_PRIVATE_KEY 自动部署到远端服务器时的私钥
DOCKER_REGISTRY_USER 推送镜像到私有仓库的用户名
DOCKER_REGISTRY_PASSWORD 对应的密码或 Token（设为 masked）

第六步：部署示例（SSH 自动部署与 GitLab Pages）

SSH 自动部署到远端服务器（常见场景）

思路是：在 CI job 里把私钥写入临时文件，设置权限，添加到 ssh-agent，然后用 rsync 或 scp 把构建产物复制到目标服务器。

deploy_production:
  stage: deploy
  image: alpine:latest
  only:
    - master
  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 your.server.com >> ~/.ssh/known_hosts
  script:
    - rsync -avz --delete dist/ [email protected]:/var/www/helloworld

GitLab Pages（静态站点）

如果你的 HelloWorld 是静态站点（比如静态 HTML），可以直接用 Pages 部署：

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r dist/* .public/
  artifacts:
    paths:
      - .public
  only:
    - master

第七步：常见错误及排查技巧（实际会遇到的坑）

  • Job 一直等待 Runner：检查项目是否关联 Runner，Runner 是否在线，以及标签是否匹配。
  • 依赖安装失败：看镜像是否缺少必要工具，考虑换镜像或在 job 里安装依赖。
  • SSH 连接失败：确认 known_hosts、私钥权限（600）、目标用户权限与目录权限。
  • 变量不生效：检查变量是否为 protected（在非受保护分支不可用）、变量名拼写是否正确。
  • 制品下载失败：检查 artifacts 配置和 job 是否执行成功。

第八步：进阶功能与优化建议

  • 并行化测试：把耗时测试拆到多个 job 并行运行，缩短流水线耗时。
  • 缓存与制品：合理使用 cache 和 artifacts，既能提升速度又能节省资源。
  • 分支策略：使用 feature 分支 + Merge Request 的工作流，保护 master/main 分支。
  • 代码质量门：在 pipeline 增加静态扫描（eslint、flake8）或安全扫描，作为合并前检查。
  • 审计与权限管理：把关键操作限制到特定人员，保护变量仅对受保护分支可见。

第九步：示例场景—从零到一完整流水线清单

下面是一份可作为检查清单的步骤，按顺序执行能快速完成集成：

  • 在 GitLab 新建项目并记录仓库地址。
  • 本地初始化项目，并推送到远程。
  • 在仓库根目录添加 .gitlab-ci.yml（先写最小示例）。
  • 确保至少有一个 Runner 可用，或者启用 Shared Runner。
  • 在 CI/CD Settings 配置必要的变量（密钥、凭据）。
  • 触发一次提交，观察 pipeline 运行日志并解决报错。
  • 根据需要配置部署 job，将制品发布到目标环境或 Pages。
  • 添加分支保护与合并请求流程，保证代码流动安全。

附录：常用命令速查表

用途 命令
初始化并推送 git init && git remote add origin URL && git add . && git commit -m “…” && git push -u origin master
查看 pipeline 日志 在 GitLab 项目页面点击 CI/CD → Pipelines → 点击对应 pipeline
在 Runner 机器注册 sudo gitlab-runner register

调试小技巧（写给会动手的人）

  • 把复杂 job 拆成多个小 job，每次排查更容易定位失败步骤。
  • 在 local 用相同的 Docker 镜像先跑一遍脚本，发现环境依赖问题更快。
  • 把 CI 日志里关键输出用 echo 打印出来，特别是环境变量和路径。

好了，接下来你可以根据上面的步骤把自己的 HelloWorld 项目接入 GitLab。我当时第一次做的时候，也是一步一步把配置加上去，遇到权限问题、Runner 不匹配、变量没生效的情况都挺常见，但把每个问题拆开看，往往十分钟能解决。若你喜欢，可以先用一个非常简单的 pipeline 验证环境，再逐步把复杂功能（容器构建、镜像推送、蓝绿部署）加入，慢慢让流水线变得可靠而高效。

更多文章