From buildkite
Converts CI/CD pipelines from GitHub Actions, Jenkins, CircleCI, Bitbucket Pipelines, and GitLab CI to Buildkite using `bk pipeline convert`. No Buildkite account required.
How this skill is triggered — by the user, by Claude, or both
Slash command
/buildkite:buildkite-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
# 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.
When a user provides a pipeline file or pastes pipeline content to convert:
/tmp/.github/workflows/ci.yml for GitHub Actions so vendor auto-detection works)bk pipeline convert -F <tempfile> --output <output-path>bk pipeline convert# 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 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.
| 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 |
# 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
# 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
| 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 |
Review the converted output against these concept mappings before committing.
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.
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.
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.
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.
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.
After conversion, review the output against these patterns:
wait or depends_on. Verify the converted ordering matches the original CI's intent.docker#v5.13.0, cache#v1.8.1). Never use unpinned or major-only versions..buildkite/scripts/.$$VAR for runtime interpolation (expanded by the agent at runtime), $VAR for upload-time interpolation (expanded during pipeline upload).group blocks to organize related steps (minimum 2 per group) with semantic emoji in labels.For a full CI migration, plan across these areas:
bk pipeline convert to translate pipeline definitionsFor cluster and queue setup, see the buildkite-platform-engineering skill. For setting up OIDC to replace static credentials, see the buildkite-secure-delivery skill.
| 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 |
npx claudepluginhub buildkite/skills --plugin buildkiteWrites and optimizes Buildkite pipeline YAML: step types, caching, parallelism, annotations, retry, dynamic pipelines, matrix builds, plugins, notifications, artifacts, concurrency.
Guides CI/CD platform selection, consolidation from multi-platform setups like CircleCI/GitLab/GitHub Actions/Jenkins, pipeline architecture design, OIDC auth, drift detection, and operational costs.
Generates multi-stage CI/CD pipelines for GitHub Actions, GitLab CI, Jenkins, CircleCI covering linting, testing, image builds, scans, and gated deployments to staging/production.