能立刻跑起来的gitlab ci配置需满足：runner已注册在线、.gitlab-ci.yml文件置于根目录、yaml缩进全用空格、stages与job阶段匹配、镜像含pytest或显式安装，且测试路径与项目结构一致。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你刚接手一个Python项目，老板说“上线前必须跑通自动化测试”，但你连.gitlab-ci.yml文件长什么样都没见过，更别说写对缩进、配对冒号、搞清stages和jobs的关系——现在就手把手带你从空白文件开始，生成一份能立刻跑起来的GitLab CI配置。
确认Runner已注册并在线
打开GitLab项目页面 → 左侧菜单点Settings → CI/CD → Runners → 查看“Available specific runners”列表里是否有状态为online且active的条目。
如果没有，说明Runner没装或没注册成功，后面所有配置都白写。此时必须先回到服务器执行sudo gitlab-runner list确认服务运行，再用sudo gitlab-runner register补注册——【URL和token必须和当前项目完全匹配，错一个字符都会触发403错误】。
创建基础.gitlab-ci.yml文件
在项目根目录新建纯文本文件，命名为.gitlab-ci.yml（注意开头是点，不是.txt）。
粘贴以下内容，保存：
stages:<br> - test<br><br>unit_test:<br> stage: test<br> image: python:3.9-slim<br> before_script:<br> - pip install -r requirements.txt<br> script:<br> - 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。
