buildkite pipeline.yml 不支持 python 逻辑，必须用 python 脚本生成合法 yaml 并通过 buildkite-agent pipeline upload 显式加载；脚本需读取 os.environ、遵守 key 格式与 if dsl 规则，并用 yaml.safe_dump 输出。
Buildkite pipeline.yml 里不能直接写 Python 逻辑
Buildkite 的 pipeline.yml 是纯 YAML，不支持变量计算、条件分支或调用 os.getenv() 这类 Python 行为。你写的 Python 脚本如果只是生成 YAML 字符串，但没让 Buildkite 加载它，那 pipeline 就还是静态的。
实操建议：
- 把 Python 脚本输出写入文件（比如
buildkite-pipeline.yml），然后在buildkite-agent pipeline upload命令中显式指定该路径 - 确保脚本在 pipeline 执行前运行——通常放在
pre-command或一个独立的commandstep 里，且该 step 必须成功退出（sys.exit(0)） - 不要依赖本地环境变量名直写进 YAML；Python 脚本里要用
os.environ.get("BUILDKITE_BRANCH")这类方式读取，再决定是否生成某个 step
用 Python 生成 pipeline 时，step 的 key 和 if 条件必须合法
Buildkite 对 key 有严格格式限制：只能含小写字母、数字、- 和 _，且不能以 - 开头；if 表达式不是 Python 表达式，而是 Buildkite 自己的 DSL（如 build.env.BRANCH == "main"）。
常见错误现象：
立即学习“Python免费学习笔记（深入）”；
- Python 脚本里拼出
key: "test-on-${BUILDKITE_BRANCH}"→ Buildkite 解析失败，报错Invalid key format - 在 YAML 里写
if: os.getenv("CI") == "buildkite"→ Buildkite 不认识os.getenv，整个 step 被跳过或报语法错 - 生成的
if条件用了单引号但漏转义，导致 YAML 解析中断
正确做法是：Python 脚本只负责拼字符串，if 写成 Buildkite 支持的格式，比如 if: build.env.BUILDKITE_TAG != null，并用 yaml.safe_dump() 输出，避免手拼引号出错。
动态 pipeline 上传后，日志和重试行为跟静态 pipeline 不同
用 buildkite-agent pipeline upload 替换原始 pipeline.yml 后，Buildkite 控制台显示的 pipeline 图是“上传时刻”的快照；后续修改 Python 脚本不影响已触发的构建，但会改变新触发的构建结构。
性能与兼容性影响：
- 上传动作本身增加约 200–500ms 延迟，对超短构建（
- 如果 Python 脚本失败（比如 JSON 解析异常、网络请求超时），整个 pipeline 上传失败，构建卡在 “waiting for pipeline” 状态，不会自动 fallback
- Buildkite 的
retry机制默认不重试 pipeline 上传步骤，需要手动加retry: { automatic: true }到该 step
示例命令写法：buildkite-agent pipeline upload buildkite-pipeline.yml || exit 1 —— 注意别漏 || exit 1，否则脚本出错却返回 0，Buildkite 以为上传成功，实际加载空 pipeline。
本地调试 Python pipeline 生成器很麻烦，但有捷径
Buildkite 的环境变量（如 BUILDKITE_COMMIT、BUILDKITE_PULL_REQUEST）在本地不存在，硬靠 export 模拟容易漏项，而且 YAML 格式错误要等上传才暴露。
推荐做法：
- Python 脚本开头加一段 mock 逻辑：
if os.getenv("CI") != "buildkite": os.environ.update({"BUILDKITE_BRANCH": "main", "BUILDKITE_PIPELINE_SLUG": "my-app"}) - 用
print(yaml.safe_dump(pipeline_dict, default_flow_style=False))直接输出到终端，肉眼核对结构 - 复制输出内容，粘贴到 yamllint.com 验证语法，比等 Buildkite 报错快得多
最容易被忽略的是 env 字段嵌套层级：Buildkite 要求每个 step 的 env 是平级键值对，不是 env: { PYTHONPATH: ... } 这种嵌套字典；Python 生成时得 flatten 处理。
