buildkite-migration

Buildkite への移行

bk pipeline convert コマンドを使用して、GitHub Actions、Jenkins、CircleCI、Bitbucket Pipelines、GitLab CI の CI/CD パイプラインを Buildkite に変換します。このコマンドはソースファイルを公開変換 API に送信します。Buildkite アカウントや API トークンは必要ありません。

クイックスタート

# 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

パイプラインの YAML 構文とステップの種類については、buildkite-pipelines スキルを参照してください。 その他の bk CLI コマンドについては、buildkite-cli スキルを参照してください。

エージェントのワークフロー

ユーザーから変換するパイプラインファイルが提供された場合、またはパイプラインの内容が貼り付けられた場合：

1. 内容を一時ファイルに書き込みます（GitHub Actions の場合は、ベンダーの自動検出が機能するように、たとえば /tmp/.github/workflows/ci.yml にします）
2. bk pipeline convert -F <tempfile> --output <output-path> を実行します
3. 出力ファイルを読み込み、YAML のコードブロックとして表示します。それ以外は何も表示しません
4. ユーザーからフィードバックを明示的に求められない限り、出力を要約、注釈、批評しないでください

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

変換コマンドは公開 API を使用するため、bk auth login は必要ありません。

基本的な使い方

bk pipeline convert -F <source-file>

主な 4 つのプロバイダーについては、ファイルパスからベンダーが自動検出されます。出力は .buildkite/pipeline.<vendor>.yml に保存されます。

サポートされているベンダー

ベンダーフラグ	ソース CI	自動検出の条件
github	GitHub Actions	.github/workflows/ パス
circleci	CircleCI	.circleci/ パス
jenkins	Jenkins	Jenkinsfile ファイル名
bitbucket	Bitbucket Pipelines	bitbucket-pipelines.yml ファイル名
gitlab	GitLab CI（ベータ）	自動検出されません
harness	Harness CI（ベータ）	自動検出されません
bitrise	Bitrise（ベータ）	自動検出されません

プロバイダーの例

# 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

フラグ

フラグ	短縮形	説明	デフォルト
--file	-F	ソースパイプラインファイルのパス	—（標準入力を使わない場合は必須）
--vendor	-v	CI ベンダー。省略した場合は自動検出されます	—
--output	-o	出力ファイルのパス	.buildkite/pipeline.<vendor>.yml
--timeout	—	キャンセルまでのタイムアウト（秒）	300

プロバイダー固有のガイダンス

コミットする前に、変換後の出力を以下の概念マッピングと照らし合わせて確認してください。

GitHub Actions

主な概念マッピング：ワークフローはパイプラインに、ジョブはステップに、uses: アクションはプラグインまたはシェルコマンドに対応します。GitHub Actions ではデフォルトでジョブが順次実行されますが、Buildkite ではデフォルトでステップが並列実行されます。変換ツールは、必要に応じて wait ステップまたは depends_on を追加し、順序を維持します。${{ secrets.X }} は、buildkite-agent secret get でアクセスする Buildkite クラスターシークレットに置き換えてください。

Jenkins

主な概念マッピング：Jenkinsfile の stage ブロックはコマンドステップまたはグループに、parallel ブロックは同じ階層のステップに（Buildkite ではデフォルトで並列実行）、post ブロックは notify: または条件付きステップに対応します。複雑な Groovy ロジックはシェルスクリプトに抽出されます。Buildkite のパイプラインは宣言型 YAML であり、プログラミング言語ではありません。

CircleCI

主な概念マッピング：jobs と workflows は 1 つの pipeline.yml にまとめられ、orbs はプラグインまたはシェルスクリプトに、executors はエージェントキューまたは docker プラグインに対応します。CircleCI の requires: は depends_on に対応します。キャッシュの構文は異なるため、変換ツールは save_cache／restore_cache を cache プラグインに置き換えます。

Bitbucket Pipelines

主な概念マッピング：pipelines.default はブランチ条件のないステップに、pipelines.branches は if: build.branch == "X" を持つステップに、pipe: の参照はプラグインまたはシェルコマンドに対応します。Bitbucket の step は、Buildkite のコマンドステップとおおむね同等です。

GitLab CI

主な概念マッピング：ステージとジョブは depends_on を持つ Buildkite のステップにまとめられ、.gitlab-ci.yml の extends: は YAML アンカーに、rules: は if: 条件に対応します。GitLab の artifacts: は Buildkite の artifact_paths に対応します。

移行したパイプラインのベストプラクティス

変換後、出力が次のパターンに沿っているか確認してください。

• デフォルトでは並列実行 — wait または depends_on で分離しない限り、Buildkite はステップを並列実行します。変換後の順序が、元の CI の意図と一致していることを確認してください。
• プラグインのバージョン指定 — プラグインのバージョンは完全な semver で固定してください（例：docker#v5.13.0、cache#v1.8.1）。バージョンを固定しない指定や、メジャーバージョンのみの指定は使用しないでください。
• コマンドの構成 — 環境変数を設定するステップでは、複数行のコマンドブロックを使用してください。複雑なロジック（コマンドが5つ以上）は、.buildkite/scripts/ 配下のスクリプトに切り出してください。
• 変数の展開 — 実行時にエージェントが展開する変数には $$VAR を、パイプラインのアップロード時に展開する変数には $VAR を使用してください。
• セキュリティ検証 — 難読化された実行パターン、Base64 エンコードされたコマンド、情報の持ち出しを試みるパターンは拒否してください。デプロイ前に変換後のパイプラインを検証してください。
• グループ化したステップ — 関連するステップを整理するには group ブロックを使用してください（各グループに2つ以上のステップが必要です）。ラベルには意味のある絵文字を使用してください。

移行計画

CI 全体を移行する場合は、次の項目を計画してください。

1. パイプラインの変換 — bk pipeline convert を使用してパイプライン定義を変換します
2. エージェントインフラストラクチャ — クラスター、キュー、エージェントをセットアップします
3. シークレット管理 — シークレットを Buildkite のクラスターシークレットに移行します
4. インテグレーション — SCM ウェブフック、通知チャンネル、アーティファクトストレージを設定します
5. テスト — 切り替え前に、既存の CI と並行して変換後のパイプラインを実行します

クラスターとキューのセットアップについては、buildkite-platform-engineering スキルを参照してください。 静的な認証情報を置き換える OIDC のセットアップについては、buildkite-secure-delivery スキルを参照してください。

よくある間違い

間違い	発生すること	修正方法
gitlab/harness/bitrise のベンダーが自動検出されない	エラー：「ファイルパスからベンダーを検出できませんでした」	--vendor gitlab、--vendor harness、または --vendor bitrise を明示的に指定します
大規模または複雑なパイプラインがタイムアウトする	タイムアウトエラーで変換に失敗します	タイムアウトを延長します：--timeout 600。必要に応じて小さなファイルに分割します
AI の出力を確認せずに受け入れる	変換後のパイプラインでステップの順序が誤っている、または依存関係が欠落します	元の CI ジョブの順序と照らし合わせて、depends_on と wait ステップを確認します
順次実行されると思い込む	ステップが並列実行され、依存関係の不足によって失敗します	依存するステップの間に wait ステップまたは depends_on を追加します
変換後のパイプラインでプラグインのバージョンが固定されていない	プラグインの互換性を損なう変更がリリースされると、ビルドが失敗します	すべてのプラグインのバージョンを完全な semver で固定します
実行時の展開が必要な箇所で $VAR を使用する	実行時ではなくアップロード時に変数が展開され、空になります	実行時に解決する必要がある変数には $$VAR を使用します

参考情報

• bk CLI のリリース — bk バイナリをダウンロードします
• Buildkite Pipelines を始める