GitLab CI Runner 是执行流水线任务的代理程序，不是流水线本身；它拉取并运行 .gitlab-ci.yml 中定义的 job，需注册在线且标签匹配，否则流水线卡在 pending 状态。
GitLab CI Runner 是什么，它和流水线是什么关系
Runner 不是流水线本身，而是执行流水线的“工人”。你在 .gitlab-ci.yml 里写的每个 job，最终都由一个已注册并在线的 Runner 拉取、运行。没有可用 Runner，流水线会卡在 “pending” 状态，连日志都看不到。
常见错误现象：job is stuck, waiting for a runner —— 这不是配置写错了，大概率是 Runner 没启动、标签没匹配、或离线了。
- Runner 分 shared（全局）、group（组级）、project（项目级）三种作用域，权限和可见性不同
- Runner 必须带至少一个
tags，而每个job必须声明tags才能被匹配到对应 Runner - Docker 类型 Runner 默认使用
docker:latest镜像拉起容器，但你可以在image:下覆盖它，比如改用python:3.11-slim
怎么让 Runner 跑起一个基础的 Python 测试 job
Runner 本身不关心语言，只负责按 YAML 指令执行 shell 命令。关键是你在 script: 里写什么、用什么环境跑。
典型误区：直接写 pytest 就跑，结果报错 command not found —— 因为默认镜像没装 pytest，也没装你的依赖。
- 必须显式安装依赖：
pip install -r requirements.txt（如果用了虚拟环境，记得先python -m venv .venv && source .venv/bin/activate） - 建议用
image: python:3.11-slim而非docker:latest，避免手动装 Python 和 pip - 加
before_script:统一做环境准备，比如- pip install --upgrade pip - 测试失败时 Runner 默认标记 job 为 failed，不用额外判断退出码 —— 但要注意 pytest 默认遇到第一个失败就停，加
-x或--maxfail=1可控
test:
image: python:3.11-slim
tags:
- docker
before_script:
- pip install --upgrade pip
- pip install -r requirements.txt
script:
- pytest tests/ --tb=short如何让多个测试 job 并行且共享产物（比如构建出的 wheel 包）
GitLab CI 默认每个 job 独立运行在干净容器中，上个 job 的文件不会自动传给下一个。想让 test 用上 build 产出的包，必须显式声明 artifacts: 和 dependencies:。
容易踩的坑：artifacts: 只上传路径，不递归打包子目录里的隐藏文件；dependencies: 写错 job 名字会导致 test job 启动后找不到文件，报 No such file or directory。
-
artifacts:下用paths:列出要保留的文件，比如- dist/*.whl -
artifacts:默认只对成功 job 生效，失败时不传；加when: always可强制上传（用于调试） - 下游 job 用
dependencies:显式声明上游 job 名，如dependencies: [build]，否则不会自动下载 artifacts - 注意
cache:和artifacts:的区别：cache 是跨 job 的临时加速（如 pip 缓存），artifacts 是明确传递给下游的产物
为什么本地能过、CI 里总 fail？几个高频兼容性点
不是代码问题，是环境差异。Runner 容器默认没 GUI、没 $HOME/.config、没系统级 locale、甚至没 /tmp 写权限（某些安全加固镜像）。
- 数据库测试常用
sqlite:///./test.db，但在 CI 容器里./可能不可写，改成sqlite:////tmp/test.db更稳 - 时间相关测试（比如
datetime.now()）在 CI 中可能因时区缺失返回 UTC，加export TZ=UTC到before_script统一时区 - 用到 secret 的测试（如 API token），绝不能硬编码，必须走 GitLab 的
CI/CD Variables，并在 job 中用variables:注入，比如API_TOKEN: $API_TOKEN - 某些 C 扩展（如 numpy、Pillow）在 slim 镜像里缺编译工具链，换用
python:3.11（非 slim）或手动apt-get update && apt-get install -y build-essential
最常被忽略的是 Runner 的 executor 类型 —— 如果你用的是 shell executor（比如在宿主机直接跑命令），它不隔离环境，看似方便，但会污染系统、无法复现、也不支持 tags 调度。生产环境请坚持用 docker 或 kubernetes executor。
