buildkite-agent

Buildkite Agent 与流水线操作

补充说明

buildkite-agent 在自有机器上执行 Buildkite 下发的 job，负责检出代码、运行命令、上传制品和回传日志。流水线步骤可以用 pipeline upload 动态生成。

常用示例

buildkite-agent --version
buildkite-agent start
buildkite-agent pipeline upload
buildkite-agent pipeline upload .buildkite/deploy.yml
buildkite-agent annotate "Deploy finished" --style success
buildkite-agent artifact upload "dist/**/*"
buildkite-agent artifact download dist/app.tar.gz .
buildkite-agent meta-data set version 1.2.3
buildkite-agent meta-data get version
buildkite-agent bootstrap

动态步骤：

buildkite-agent pipeline upload <<'YAML'
steps:
  - label: ":test_tube: Test"
    command: npm test
  - wait
  - label: ":rocket: Deploy"
    command: ./deploy.sh
    agents:
      queue: deploy
YAML

易错点与排错

• Agent token 和 API token 权限不同；在 agent 上只配置 agent token。
• queue/tag 不匹配时 job 不会分配给该 agent；先看 agent 的标签。
• agent 每次 job 可能重新 checkout；需要保留的状态放 artifacts 或外部存储。
• pipeline upload 生成的步骤是动态的；上传失败时后续步骤根本不存在。
• artifact 路径相对工作目录；通配符不匹配时上传成功但内容为空。
• meta-data 只在同一 build 内有效；跨 build 用 artifacts 或外部系统。
• 自托管 agent 的环境和镜像要自己维护；不要假设有 GitHub 托管 Runner 的预装工具。
• 并发和队列配置不当会导致 job 饥饿；观察 agent 利用率和 queue 深度。

相关命令

• github-actions — GitHub 流水线
• gitlab-ci — GitLab 流水线
• docker — 容器化 agent