配置GitLab CI最怕什么？文件写好了，Runner没注册；Runner注册了，缩进用错了；缩进改对了，测试路径又不对。要生成一份能立刻跑起来的.gitlab-ci.yml，其实只需要盯住几个关键点：Runner已注册且在线、配置文件放在项目根目录、YAML缩进全用空格、stages与job阶段匹配、镜像里包含pytest（或显式安装），以及测试路径与项目结构一致。下面就从空白文件开始，一步步拆解。

刚接手一个Python项目，老板说“上线前必须跑通自动化测试”，但你可能连.gitlab-ci.yml长什么样都没见过，更别说搞清楚缩进、冒号、stages和jobs的关系。别急，我们从零开始。

确认Runner已注册并在线

打开GitLab项目页面，左侧菜单点Settings → CI/CD → Runners，在“A vailable specific runners”列表里检查是否有状态为online且active的条目。如果没有，说明Runner没装或没注册成功，后面所有配置都白写。

此时必须先回到服务器执行sudo gitlab-runner list确认服务运行，再用sudo gitlab-runner register补注册——【URL和token必须和当前项目完全匹配，错一个字符都会触发403错误】。

创建基础.gitlab-ci.yml文件

在项目根目录新建纯文本文件，命名为.gitlab-ci.yml（注意开头是点，不是.txt）。粘贴以下内容保存：

stages:
  - test

unit_test:
  stage: test
  image: python:3.9-slim
  before_script:
    - pip install -r requirements.txt
  script:
    - python -m pytest tests/ --tb=short

这五行缩进全用空格（不能用Tab），每行末尾不能有多余空格。YAML对这些极其敏感——【少一个空格或混入Tab，流水线直接报错“did not find expected key”】。

适配你的项目结构

第一步：检查requirements.txt是否存在。运行ls requirements.txt，如果提示“No such file”，就删掉before_script里那一行pip安装语句，改成- pip install pytest——很多小项目根本没写依赖文件，硬装会失败。

第二步：定位测试目录。你的测试文件不在tests/下？常见位置还有test/、src/tests/、甚至app/tests/。把pytest tests/里的tests/替换成你实际路径，比如pytest test/。

第三步：没有测试文件怎么办？先建个占位测试：mkdir -p tests && echo "def test_dummy(): assert True" > tests/test_dummy.py。不然流水线走到pytest那步会报“no tests found”，整个job标红失败。

提交并触发第一次流水线

第一步：git add .gitlab-ci.yml
第二步：git commit -m "add basic CI config"
第三步：git push origin main

推送后立刻刷新GitLab页面，左上角会出现黄色“running”图标。点击进去就能看到实时日志——如果卡在Preparing environment超过2分钟，大概率是Runner没选对；如果报command not found: pytest，说明镜像里没预装pytest，得在before_script里补- pip install pytest。