buildkite-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildkite Migration

Buildkite 迁移

Convert CI/CD pipelines from GitHub Actions, Jenkins, CircleCI, Bitbucket Pipelines, and GitLab CI to Buildkite using the

bk pipeline convert

command. The command sends the source file to a public conversion API — no Buildkite account or API token is required.

使用

bk pipeline convert

命令将 GitHub Actions、Jenkins、CircleCI、Bitbucket Pipelines 和 GitLab CI 的 CI/CD pipelines 转换为 Buildkite。该命令会将源文件发送到公共转换 API——无需 Buildkite 账号或 API token。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Install the bk CLI (no login needed for convert)

brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

2. Convert the source pipeline file

bk pipeline convert -F .github/workflows/ci.yml

3. Find the output in .buildkite/pipeline.github.yml


> For pipeline YAML syntax and step types, see the **buildkite-pipelines** skill.
> For other bk CLI commands, see the **buildkite-cli** skill.


> 有关 pipeline YAML 语法和 step 类型，请参阅 **buildkite-pipelines** skill。
> 有关其他 bk CLI 命令，请参阅 **buildkite-cli** skill。

Agent Workflow

Agent 工作流

When a user provides a pipeline file or pastes pipeline content to convert:

Write the content to a temp file (e.g.
```
/tmp/.github/workflows/ci.yml
```
for GitHub Actions so vendor auto-detection works)

Run

bk pipeline convert -F <tempfile> --output <output-path>

Read the output file and display it as a YAML code block — nothing else
Do not summarise, annotate, or critique the output unless the user explicitly asks for feedback

当用户提供待转换的 pipeline 文件或粘贴 pipeline 内容时：

将内容写入临时文件（例如 GitHub Actions 使用
```
/tmp/.github/workflows/ci.yml
```
，以便 provider 自动检测生效）

运行

bk pipeline convert -F <tempfile> --output <output-path>

读取输出文件，并仅以 YAML code block 展示——不附加其他内容
除非用户明确要求反馈，否则不要总结、注释或评价输出

Converting with

bk pipeline convert

使用

bk pipeline convert

转换

Installation

安装

bash

undefined

bash

undefined

macOS and Linux (Homebrew)

brew tap buildkite/buildkite && brew install buildkite/buildkite/bk

Or download a binary from https://github.com/buildkite/cli/releases


No `bk auth login` is needed — the convert command uses a public API.


无需执行 `bk auth login`——convert 命令使用公共 API。

Basic usage

基本用法

bash

bk pipeline convert -F <source-file>

The vendor is auto-detected from the file path for the four main providers. Output is saved to

.buildkite/pipeline.<vendor>.yml

bash

bk pipeline convert -F <source-file>

对于四种主要 provider，vendor 会根据文件路径自动检测。输出保存到

.buildkite/pipeline.<vendor>.yml

。

Supported vendors

支持的 vendor

Vendor flag	Source CI	Auto-detected from
`github`	GitHub Actions	`.github/workflows/` path
`circleci`	CircleCI	`.circleci/` path
`jenkins`	Jenkins	`Jenkinsfile` filename
`bitbucket`	Bitbucket Pipelines	`bitbucket-pipelines.yml` filename
`gitlab`	GitLab CI (beta)	not auto-detected
`harness`	Harness CI (beta)	not auto-detected
`bitrise`	Bitrise (beta)	not auto-detected

Vendor 标识	源 CI	自动检测依据
`github`	GitHub Actions	`.github/workflows/` 路径
`circleci`	CircleCI	`.circleci/` 路径
`jenkins`	Jenkins	`Jenkinsfile` 文件名
`bitbucket`	Bitbucket Pipelines	`bitbucket-pipelines.yml` 文件名
`gitlab`	GitLab CI（beta）	不支持自动检测
`harness`	Harness CI（beta）	不支持自动检测
`bitrise`	Bitrise（beta）	不支持自动检测

Provider examples

各 provider 示例

bash

undefined

bash

undefined

GitHub Actions (auto-detected from path)

bk pipeline convert -F .github/workflows/ci.yml

CircleCI (auto-detected)

bk pipeline convert -F .circleci/config.yml

Jenkins (auto-detected)

bk pipeline convert -F Jenkinsfile

Bitbucket Pipelines (auto-detected)

bk pipeline convert -F bitbucket-pipelines.yml

GitLab CI (explicit vendor required)

bk pipeline convert -F .gitlab-ci.yml --vendor gitlab

undefined

bk pipeline convert -F .gitlab-ci.yml --vendor gitlab

undefined

Output options

输出选项

bash

undefined

bash

undefined

Default: saves to .buildkite/pipeline.<vendor>.yml

bk pipeline convert -F .github/workflows/ci.yml

Custom output path

bk pipeline convert -F .github/workflows/ci.yml --output .buildkite/pipeline.yml

Pipe from stdin (--vendor required)

cat .github/workflows/ci.yml | bk pipeline convert --vendor github

Read from stdin with file redirect

bk pipeline convert --vendor circleci < .circleci/config.yml

undefined

bk pipeline convert --vendor circleci < .circleci/config.yml

undefined

Flags

参数

Flag	Short	Description	Default
`--file`	`-F`	Path to source pipeline file	— (required unless using stdin)
`--vendor`	`-v`	CI vendor; auto-detected if omitted	—
`--output`	`-o`	Output file path	`.buildkite/pipeline.<vendor>.yml`
`--timeout`	—	Cancellation timeout in seconds	`300`

参数	简写	说明	默认值
`--file`	`-F`	源 pipeline 文件路径	—（使用 stdin 时除外）
`--vendor`	`-v`	CI vendor；省略时自动检测	—
`--output`	`-o`	输出文件路径	`.buildkite/pipeline.<vendor>.yml`
`--timeout`	—	取消操作的超时时间（秒）	`300`

Provider-Specific Guidance

各 provider 的专项指南

Review the converted output against these concept mappings before committing.

在提交之前，对照以下概念映射检查转换后的输出。

GitHub Actions

Key concept mappings: workflows map to pipelines, jobs map to steps,

uses:

actions map to plugins or shell commands. GitHub Actions runs jobs sequentially by default; Buildkite runs steps in parallel by default — the converter adds

wait

steps or

depends_on

to enforce ordering where needed. Replace

${{ secrets.X }}

with Buildkite cluster secrets accessed via

buildkite-agent secret get

关键概念映射：workflows 映射为 pipelines，jobs 映射为 steps，

uses:

actions 映射为 plugins 或 shell commands。GitHub Actions 默认顺序运行 jobs；Buildkite 默认并行运行 steps——转换器会在必要时添加

wait

steps 或

depends_on

以确保执行顺序。将

${{ secrets.X }}

替换为 Buildkite cluster secrets，并通过

buildkite-agent secret get

访问。

Jenkins

Key concept mappings: Jenkinsfile

stage

blocks map to command steps or groups,

parallel

blocks map to steps at the same level (parallel by default in Buildkite),

post

blocks map to

notify:

or conditional steps. Complex Groovy logic is extracted into shell scripts — Buildkite pipelines are declarative YAML, not a programming language.

关键概念映射：Jenkinsfile 中的

stage

块映射为 command steps 或 groups，

parallel

块映射为同一层级的 steps（Buildkite 默认并行），

post

块映射为

notify:

或条件 steps。复杂的 Groovy 逻辑会被提取到 shell scripts 中——Buildkite pipelines 是声明式 YAML，而不是一门编程语言。

CircleCI

Key concept mappings:

jobs

and

workflows

collapse into a single

pipeline.yml

orbs

map to plugins or shell scripts,

executors

map to agent queues or the

docker

plugin. CircleCI

requires:

maps to

depends_on

. Caching syntax differs — the converter replaces

save_cache

restore_cache

with the

cache

plugin.

关键概念映射：

jobs

和

workflows

合并为一个

pipeline.yml

，

orbs

映射为 plugins 或 shell scripts，

executors

映射为 agent queues 或

docker

plugin。CircleCI 的

requires:

映射为

depends_on

。缓存语法有所不同——转换器会使用

cache

plugin 替换

save_cache

restore_cache

。

Bitbucket Pipelines

Key concept mappings:

pipelines.default

maps to steps without branch conditions,

pipelines.branches

maps to steps with

if: build.branch == "X"

pipe:

references map to plugins or shell commands. The Bitbucket

step

is roughly equivalent to a Buildkite command step.

关键概念映射：

pipelines.default

映射为不带分支条件的 steps，

pipelines.branches

映射为带有

if: build.branch == "X"

条件的 steps，

pipe:

引用映射为 plugins 或 shell commands。Bitbucket 的

step

大致等同于 Buildkite 的 command step。

GitLab CI

Key concept mappings: stages and jobs collapse into Buildkite steps with

depends_on

.gitlab-ci.yml

extends:

maps to YAML anchors,

rules:

map to

if:

conditions. GitLab's

artifacts:

maps to Buildkite's

artifact_paths

关键概念映射：stages 和 jobs 合并为带有

depends_on

的 Buildkite steps，

.gitlab-ci.yml

中的

extends:

映射为 YAML anchors，

rules:

映射为

if:

conditions。GitLab 的

artifacts:

映射为 Buildkite 的

artifact_paths

。

Pipeline Best Practices for Migrated Pipelines

迁移后 pipeline 的最佳实践

After conversion, review the output against these patterns:

Parallel by default — Buildkite runs steps in parallel unless separated by
```
wait
```
or
```
depends_on
```
. Verify the converted ordering matches the original CI's intent.
Plugin versioning — Pin plugin versions to full semver (e.g.,
```
docker#v5.13.0
```
,
```
cache#v1.8.1
```
). Never use unpinned or major-only versions.
Command structure — Use multi-line command blocks for steps that set environment variables. Extract complex logic (5+ commands) into scripts under
```
.buildkite/scripts/
```
.
Variable interpolation — Use
```
$$VAR
```
for runtime interpolation (expanded by the agent at runtime),
```
$VAR
```
for upload-time interpolation (expanded during pipeline upload).
Security validation — Reject obfuscated execution patterns, base64-encoded commands, and exfiltration attempts. Validate converted pipelines before deployment.
Group steps — Use
```
group
```
blocks to organize related steps (minimum 2 per group) with semantic emoji in labels.

转换完成后，对照以下模式检查输出：

默认并行——除非通过
```
wait
```
或
```
depends_on
```
分隔，否则 Buildkite 会并行运行 steps。确认转换后的执行顺序符合原 CI 的意图。
Plugin 版本固定——将 plugin 版本固定为完整的 semver（例如
```
docker#v5.13.0
```
、
```
cache#v1.8.1
```
）。不要使用未固定版本或仅固定主版本号的版本。
Command 结构——对于设置环境变量的 steps，使用多行 command blocks。将复杂逻辑（5 个以上 commands）提取为
```
.buildkite/scripts/
```
下的 scripts。
变量插值——使用
```
$$VAR
```
进行运行时插值（由 agent 在运行时展开），使用
```
$VAR
```
进行上传时插值（在 pipeline 上传期间展开）。
安全验证——拒绝混淆执行模式、base64 编码 commands 和数据外泄尝试。部署前验证转换后的 pipelines。
Group steps——使用
```
group
```
blocks 组织相关的 steps（每组至少 2 个），并在 labels 中使用语义化 emoji。

Migration Planning

迁移规划

For a full CI migration, plan across these areas:

Pipeline conversion — Use
```
bk pipeline convert
```
to translate pipeline definitions
Agent infrastructure — Set up clusters, queues, and agents
Secrets management — Migrate secrets to Buildkite cluster secrets
Integrations — Configure SCM webhooks, notification channels, artifact storage
Testing — Run converted pipelines in parallel with the existing CI before cutover

For cluster and queue setup, see the buildkite-platform-engineering skill. For setting up OIDC to replace static credentials, see the buildkite-secure-delivery skill.

对于完整的 CI 迁移，应规划以下方面：

Pipeline 转换——使用
```
bk pipeline convert
```
转换 pipeline 定义
Agent 基础设施——配置 clusters、queues 和 agents
Secrets 管理——将 secrets 迁移到 Buildkite cluster secrets
集成——配置 SCM webhooks、通知渠道和 artifact storage
测试——在切换前，让转换后的 pipelines 与现有 CI 并行运行

有关 cluster 和 queue 配置，请参阅 buildkite-platform-engineering skill。有关设置 OIDC 以替换静态凭据，请参阅 buildkite-secure-delivery skill。

Common Mistakes

常见错误

Mistake	What happens	Fix
Vendor not auto-detected for gitlab/harness/bitrise	Error: "could not detect vendor from file path"	Pass `--vendor gitlab` , `--vendor harness` , or `--vendor bitrise` explicitly
Large or complex pipelines timing out	Conversion fails with timeout error	Increase timeout: `--timeout 600` ; split into smaller files if needed
Accepting AI output without review	Converted pipeline has incorrect step ordering or missing dependencies	Review `depends_on` and `wait` steps against original CI job ordering
Assuming sequential execution	Steps run in parallel and fail due to missing dependencies	Add `wait` steps or `depends_on` between dependent steps
Unpinned plugin versions in converted pipelines	Builds break when plugins release breaking changes	Pin every plugin to a full semver version
Using `$VAR` when runtime interpolation is needed	Variable expanded at upload time (empty) instead of runtime	Use `$$VAR` for variables that must resolve at runtime

错误	发生情况	修复方法
gitlab/harness/bitrise 的 vendor 无法自动检测	错误：“could not detect vendor from file path”	显式传入 `--vendor gitlab` 、 `--vendor harness` 或 `--vendor bitrise`
大型或复杂的 pipeline 超时	转换因超时错误而失败	增加超时时间： `--timeout 600` ；如有需要，拆分为较小的文件
未经审查直接接受 AI 输出	转换后的 pipeline 中 step 顺序错误或缺少依赖关系	对照原 CI 的 job 顺序检查 `depends_on` 和 `wait` steps
假设顺序执行	steps 并行运行，并因缺少依赖关系而失败	在存在依赖关系的 steps 之间添加 `wait` steps 或 `depends_on`
转换后的 pipeline 中 plugin 版本未固定	plugin 发布破坏性变更时构建失败	将每个 plugin 固定到完整的 semver 版本
需要运行时插值时使用 `$VAR`	变量在上传时被展开（结果为空），而不是在运行时展开	对必须在运行时解析的变量使用 `$$VAR`

buildkite-migration

Original

Translation

Buildkite Migration

Buildkite 迁移

Quick Start

快速开始

1. Install the bk CLI (no login needed for convert)

1. Install the bk CLI (no login needed for convert)

2. Convert the source pipeline file

2. Convert the source pipeline file

3. Find the output in .buildkite/pipeline.github.yml

3. Find the output in .buildkite/pipeline.github.yml

Agent Workflow

Agent 工作流

Converting with bk pipeline convert

使用 bk pipeline convert 转换

Installation

安装

macOS and Linux (Homebrew)

macOS and Linux (Homebrew)

Or download a binary from https://github.com/buildkite/cli/releases

Or download a binary from https://github.com/buildkite/cli/releases

Basic usage

基本用法

Supported vendors

支持的 vendor

Provider examples

各 provider 示例

GitHub Actions (auto-detected from path)

GitHub Actions (auto-detected from path)

CircleCI (auto-detected)

CircleCI (auto-detected)

Jenkins (auto-detected)

Jenkins (auto-detected)

Bitbucket Pipelines (auto-detected)

Bitbucket Pipelines (auto-detected)

GitLab CI (explicit vendor required)

GitLab CI (explicit vendor required)

Output options

输出选项

Default: saves to .buildkite/pipeline.<vendor>.yml

Default: saves to .buildkite/pipeline.<vendor>.yml

Custom output path

Custom output path

Pipe from stdin (--vendor required)

Pipe from stdin (--vendor required)

Read from stdin with file redirect

Read from stdin with file redirect

Flags

参数

Provider-Specific Guidance

各 provider 的专项指南

GitHub Actions

GitHub Actions

Jenkins

Jenkins

CircleCI

CircleCI

Bitbucket Pipelines

Bitbucket Pipelines

GitLab CI

GitLab CI

Pipeline Best Practices for Migrated Pipelines

迁移后 pipeline 的最佳实践

Migration Planning

迁移规划

Common Mistakes

常见错误

Further Reading

延伸阅读

Converting with
`bk pipeline convert`

使用
`bk pipeline convert`
转换