Bitbucket Pipelinesの「修正→プッシュ→失敗→修正」という地獄からの脱却 ― `bitbucket-pipelines-runner`でローカル開発を極める
「またパイプラインが落ちた。原因を探るためにまたコミットを積むのか？」
CI/CDエンジニアなら誰もが一度は経験する、あの絶望的な待ち時間。クラウド上のコンテナが立ち上がり、依存関係をダウンロードし、ようやくエラーログを目にしたときには10分が経過している。これでは開発速度など上がるはずがない。
真のDevOpsスペシャリストは、クラウドを「最終確認の場」と定義し、「実行の場」は常に手元（ローカル）に置いておく。
今回は、Bitbucket Pipelinesのビルドをローカルで完全再現し、あなたの開発サイクルを劇的に加速させる『bitbucket-pipelines-runner』の極意を伝授する。
—
1. なぜ「ローカル実行」が聖域なのか
クラウド環境のCIはブラックボックスになりがちだ。キャッシュの挙動、環境変数の不整合、特定のOSライブラリ不足。これらをクラウド上でデバッグするのは、目隠しをして迷路を解くようなものだ。
`bitbucket-pipelines-runner`を活用すれば、CI環境と完全に同一のDockerコンテナをローカルで起動できる。つまり、「プッシュする前に、成功することが確定している状態」を作り出せるのだ。
2. セットアップ：ローカル環境をCIの鏡にする
まずは、ローカル環境がCIの姿を映し出すための準備から始める。
実用的なローカル実行のコマンド
CLIツール（`docker`がインストールされていることが前提）を使用し、`bitbucket-pipelines.yml`の内容を検証する。
特定のステップをローカルで実行（例：buildステップ）
–envでCIと同一の環境変数を注入するのがミソ
docker run -it –rm \
-v $(pwd):/opt/atlassian/bitbucketci/agent/build \
-e CI=true \
-e BUILD_ENV=development \
atlassian/pipelines-runner:latest \
/bin/bash
- ポイント: `-v $(pwd):/opt/atlassian/bitbucketci/agent/build` で、ローカルのソースをコンテナ内へマウントする。これにより、コンテナ内での変更が即座にホスト側に反映される。
3. 生産性を10倍にする「神設定」と運用ルール
ただ動かすだけではアマチュアだ。チームの生産性を底上げする「設定の作法」を公開する。
YAMLの構造化：多段階ビルドのベストプラクティス
巨大なYAMLはメンテナンスの墓場だ。再利用可能な`definitions`を活用し、ステップをモジュール化せよ。
bitbucket-pipelines.yml
definitions:
steps:
- step: &unit-test
name: Unit Tests
image: node:18-alpine
script:
- npm ci
- npm test
- step: &lint
name: Linting
script:
- npm run lint
pipelines:
default:
- step: lint
- step: unit-test
- プロの知見: CI/CD設定は「宣言的」であるべきだ。ロジックをYAMLに書くのではなく、シェルスクリプト（`scripts/ci/test.sh`など）に追い出し、YAMLからはそれを呼ぶだけにせよ。そうすれば、ローカルでの実行コマンドが統一される。
4. 現場で震えるほど役立つ「隠れたハック」
① キーボードショートカットの活用
Bitbucketの画面上でパイプラインを操作する際、マウスを使っていないか？
- `Shift + ?`: Bitbucketの全ショートカットを表示。
- `r`: 現在の画面でパイプラインの再実行（Rerun）。これを知っているだけで、リロード回数が減る。
② ローカルキャッシュの疑似再現
クラウドのキャッシュを模倣するには、ローカルのコンテナ内にディレクトリをマウントしておくのが定石だ。
キャッシュ設定のローカルテスト用マッピング
- v: ./node_modules_cache:/home/node/.npm
これをローカル実行時に含めることで、依存関係の解決速度をクラウドと同じレベルに引き上げられる。
③ チーム共通の「神プラグイン」
VS Codeを使っているなら、「YAML」拡張機能（by Red Hat）を入れ、以下の設定をワークスペース設定（`.vscode/settings.json`）に追加せよ。
{
“yaml.schemas”: {
“https://bitbucket.org/atlassian/pipelines-schema/raw/master/bitbucket-pipelines.schema.json”: “bitbucket-pipelines.yml”
}
}
これで、YAMLを書いている最中にリアルタイムでバリデーションが走り、構文エラーを即座に特定できる。
5. 最後に：テックリードからの提言
CI/CDパイプラインは、単なる自動化ツールではない。チームの「信頼」をビルドする基盤だ。
パイプラインが壊れるたびに「クラウドのせいだ」と嘆く時間はもう終わりにしよう。`bitbucket-pipelines-runner`でローカルを整備し、CIを完全にコントロール下に置く。その余裕こそが、より良いコード、より強固なアーキテクチャを生み出すための余白となる。
さあ、今すぐターミナルを開き、ローカルでのビルドを成功させろ。その最初の一歩が、あなたのチームの開発スピードを、異次元へと進化させる。