.gitlab-ci.yml必须命名为该文件且置于项目根目录，否则流水线不触发；配置须含stages和至少一个job，artifacts用于跨job传递产物，Go构建需禁用CGO并指定GOOS=linux确保静态编译。
GitLab CI 配置文件必须叫 .gitlab-ci.yml，且放在项目根目录
GitLab 不会识别其他名称或路径下的 CI 配置。常见错误是误命名为 gitlab-ci.yml（缺点）、.gitlab-ci.yaml（后缀错）或放在 ci/ 子目录里。一旦命名或位置不对，流水线根本不会触发。
配置中必须明确声明 stages 和至少一个 job，否则即使文件存在也视为无效。建议初始版本先写最简可用结构：
stages: - build - deploy <p>build-app: stage: build image: golang:1.21-alpine script:</p><ul><li>go mod download</li><li>CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o gin-app . artifacts:</li><li>gin-app</li></ul><p>deploy-to-staging: stage: deploy image: alpine:3.18 before_script:</p><ul><li>apk add --no-cache openssh-client script:</li><li>scp -o StrictHostKeyChecking=no gin-app user@staging-server:/opt/app/gin-app</li><li>ssh -o StrictHostKeyChecking=no user@staging-server "systemctl restart gin-app.service"
注意：artifacts 是跨 job 传递构建产物的关键，漏掉会导致 deploy-to-staging 找不到 gin-app 二进制文件。
Go 构建阶段要禁用 CGO 并指定 GOOS=linux
默认开启 CGO 会让 Go 编译出依赖 glibc 的二进制，而生产环境容器（如 alpine）使用的是 musl libc，直接运行会报 no such file or directory —— 实际是动态链接器找不到，不是文件真丢了。
必须在 script 中显式设置：
-
CGO_ENABLED=0：关闭 C 语言交互，强制纯静态链接 -
GOOS=linux：确保目标平台为 Linux（即使本地是 macOS/Windows） -
-ldflags="-w -s"：剥离调试符号和 DWARF 信息，减小体积、加快启动
如果项目里用了 cgo 特性（比如调用 SQLite 或某些加密库），不能简单关 CGO，得换基础镜像为 golang:1.21-slim + debian 系，并在运行镜像中补全 libc6，但会增大镜像体积——这是权衡点，不是所有 Gin 项目都需要。
部署 job 必须区分环境，且避免硬编码服务器地址
把 staging-server、user、/opt/app/ 这类值写死在 .gitlab-ci.yml 里，会导致测试环境配置污染生产流程，也违反安全原则。
正确做法是用 GitLab 的 environment + variables 组合：
- 在 GitLab 项目 Settings → CI/CD → Variables 中定义：
STAGING_HOST、STAGING_USER、STAGING_DEPLOY_PATH - 在 deploy job 中引用：
ssh $STAGING_USER@$STAGING_HOST "systemctl restart gin-app.service" - 用
only或rules控制触发分支，例如只对main推送才部署到生产，develop分支只部署到预发
更进一步，可以按环境拆成不同 job，比如 deploy-to-staging 和 deploy-to-prod，各自绑定对应变量组和保护规则，避免误操作。
健康检查没配好，K8s 滚动更新会卡住
如果你的 Gin 应用最终跑在 Kubernetes 上，而 .gitlab-ci.yml 里只负责推镜像、不负责更新 K8s 资源，那很容易出现“新 Pod 一直 Pending”或“旧 Pod 被删光、新 Pod 启不来”的情况。
根本原因是缺少就绪探针（readinessProbe）和存活探针（livenessProbe）。Gin 默认不暴露健康端点，你得自己加路由：
router.GET("/healthz", func(c *gin.Context) {
c.Status(http.StatusOK)
})然后在 K8s Deployment 的 YAML 中配好：
readinessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 15
periodSeconds: 20CI 流水线本身不处理这些，但如果你跳过这步，后续任何自动部署都会因 K8s 认为 Pod “未就绪”而停滞——这个坑往往在上线前最后一刻才暴露。
