GitLab CI/CD 流水线必须使用根目录下的 .gitlab-ci.yml 文件，严格区分大小写；image 和 before_script 共同定义执行环境；应使用 rules 替代已废弃的 only/except；调试时优先输出环境信息定位隐含差异。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

豆包AI本身不提供 GitLab CI/CD 配置能力，也不能“写”流水线——它只能帮你理解、生成或调试 .gitlab-ci.yml 文件内容。

GitLab 流水线文件必须叫 .gitlab-ci.yml

这是硬性约定，文件名错一个字符（比如 .gitlab-ci.yaml 或 gitlab-ci.yml 缺点）都会导致 GitLab 完全不识别。路径也必须放在仓库根目录，子目录里的不会被加载。

• 常见错误现象：pipeline not triggered 或 Web UI 显示 “No pipelines yet”，但提交已成功推送
• 检查方式：在 GitLab 项目主页 → CI/CD → Pipelines 页面右上角点 “Run pipeline”，如果提示 “No configuration file found”，就是名字或位置错了
• 注意大小写：YML 不等于 yml，Linux 环境下严格区分

image 和 before_script 决定环境一致性

流水线跑在哪，取决于 image；而依赖安装、环境变量设置等靠 before_script。很多人直接照搬本地命令，结果在 CI 中失败，核心原因就是没意识到这两者共同定义了执行上下文。

• 典型翻车场景：本地用 npm run build 成功，CI 报 command not found: npm —— 因为没设 image: node:18，默认镜像是 alpine，没装 Node
• before_script 里不要写交互式命令（如 npm login），CI 环境无 TTY；敏感操作应改用 CI_JOB_TOKEN 或 CI_REGISTRY_PASSWORD 等预置变量
• 镜像选轻量版更稳：比如 node:18-slim 比 node:18 启动快、体积小，且不含不必要的包，减少干扰

job 级别的 rules 比全局 only/except 更可靠

GitLab 已标记 only 和 except 为 legacy，新配置必须用 rules，否则某些触发条件（如合并请求事件、计划流水线）会失效。

Workspace Git Setup

一键在任意工作目录中设置 Git 跟踪，并附带安全为重点的 .gitignore（包括凭证、TLS/SSH 私钥、令牌、运行时缓存和 PID 等）

下载

立即进入“豆包AI人工智官网入口”；

立即学习“豆包AI人工智能在线问答入口”；

• 常见错误现象：MR 提交后没自动触发测试 job，但 push 到 main 就有——大概率是用了 only: [main]，它不响应 merge_requests 事件
• 正确写法示例：

  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "src/**/*"

  表示仅当 MR 修改了 src 下文件时才运行该 job
• rules 是顺序匹配，第一条满足即生效；- when: never 可用于排除，别漏掉 else 分支导致意外跳过

真正卡住人的往往不是语法，而是环境隔离带来的隐含差异：本地 PATH 有全局 Python，CI 里只有镜像自带的；本地用 shell alias，CI 里得写全路径；甚至时区、locale 设置都可能影响日志解析。每次调试前，先加个 script: [env, pwd, which python, python --version] 看清实际执行现场，比猜快得多。