| name | buildkite-migration |
| description | This skill should be used when the user asks to "migrate to Buildkite", "convert pipelines from Jenkins", "convert GitHub Actions workflows", "convert CircleCI config", "convert Bitbucket Pipelines", "convert GitLab CI", "migrate CI/CD to Buildkite", "switch from Jenkins to Buildkite", "move from GitHub Actions", "plan a CI migration", "convert my CI config", "bk pipeline convert", or "what's the Buildkite equivalent of". Also use when the user mentions migration planning, CI conversion, pipeline conversion, converting workflows, or asks about translating CI/CD configuration from another provider to Buildkite.
|
Buildkite Migration
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.
Quick Start
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk
bk pipeline convert -F .github/workflows/ci.yml
For pipeline YAML syntax and step types, see the buildkite-pipelines skill.
For other bk CLI commands, see the buildkite-cli skill.
Agent Workflow
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
Converting with bk pipeline convert
Installation
brew tap buildkite/buildkite && brew install buildkite/buildkite/bk
No bk auth login is needed — the convert command uses a public API.
Basic usage
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.
Supported vendors
| 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 |
Provider examples
bk pipeline convert -F .github/workflows/ci.yml
bk pipeline convert -F .circleci/config.yml
bk pipeline convert -F Jenkinsfile
bk pipeline convert -F bitbucket-pipelines.yml
bk pipeline convert -F .gitlab-ci.yml --vendor gitlab
Output options
bk pipeline convert -F .github/workflows/ci.yml
bk pipeline convert -F .github/workflows/ci.yml --output .buildkite/pipeline.yml
cat .github/workflows/ci.yml | bk pipeline convert --vendor github
bk pipeline convert --vendor circleci < .circleci/config.yml
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 |
Provider-Specific Guidance
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.
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.
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.
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.
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.
Pipeline Best Practices for Migrated Pipelines
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.
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.
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 |
Further Reading
