技術資料

Bitbucket Cloudでは、Pipelinesを使うと、コードをpushしたときに決めておいたコマンドを自動実行できます。

今回は事前学習で試した最小構成をもとに、PHPのバージョンとファイルの存在を確認するCIを作ってみます。成功する構成を動かし、わざと失敗させ、ログを確認して修正するところまでを扱います。

BitbucketのRepositoryやbranch、Pull Requestの基本については、以前の「GitHub経験者向けBitbucket入門」を参照してください。設定と画面の説明は、2026年9月28日時点のAtlassian公式資料をもとにしています。

Pipelinesで何を設定するのか

Bitbucket Pipelinesは、Bitbucket Cloudに組み込まれたCI/CDの機能です。Repositoryに保存した設定ファイルに従い、コンテナ内でコマンドを実行します。GitHub Actionsを使ったことがあるなら、変更に合わせて検証処理を動かす機能、と考えると分かりやすいかと思います。

設定ファイルには、実行環境、実行するタイミング、処理のまとまりであるstep、実行するコマンドを記述します。テストやビルドも実行できますが、今回はPipelinesの動きを理解するため、環境確認とファイル存在確認だけに絞ります。

練習用Repositoryを用意し、次の点を確認してください。

• Repositoryをローカルへcloneし、作業用branchへpushできること
• Repository直下にREADME.mdがあり、Gitで管理されていること
• 対象RepositoryでPipelinesが有効になっていること

Pipelinesが無効なら、Repository settingsのPipelinesにあるSettingsから、Enable Pipelinesを有効にします。設定を変更できない場合はRepositoryの管理者へ確認してください。初めて設定する場合は、RepositoryのPipelinesからCreate your first pipelineへ進み、画面上のエディターでYAMLを作る方法もあります。

実行時間にはプランごとの利用枠があります。繰り返し試す場合は、Atlassianのプラン・課金の説明とWorkspaceの利用状況を確認しておきましょう。

最小の設定ファイルを作る

Repository直下にbitbucket-pipelines.ymlを作成します。今回はローカルでファイルを編集し、commitしてpushする方法で進めます。既存のPipelines設定がある場合は、練習用Repositoryで試してください。

image: php:8.3-cli

pipelines:
  default:
    - step:
        name: PHP environment check
        script:
          - php -v
          - test -f README.md
          - echo "Pipeline completed successfully."

それぞれの項目の役割は次のとおりです。

• image: コマンドを実行するDockerイメージ。今回はPHP 8.3系のCLI版を使います
• pipelines: 実行条件と処理をまとめる項目
• default: ブランチへのpushに対して実行する設定
• step: 一つの処理単位。nameで画面に表示する名前を付けます
• script: step内で順番に実行するコマンド

今回のようにdefaultだけを定義した場合、各ブランチへのpushでこの処理が動きます。tagのpushは対象外です。別途branchesにブランチ専用の定義を追加した場合は、一致するブランチではそちらが使われます。

php:8.3-cliはPHP 8.3系を指定するタグです。パッチバージョンまで固定しているわけではないため、実際のバージョンはphp -vのログで確認します。

scriptに書いたコマンドは、今回指定したLinuxコンテナ内で実行されます。手元でPowerShellを使っていても、この部分はPowerShellのコマンドではありません。例えばtest -fは、指定した通常ファイルが存在するかを確認するシェルのコマンドです。

pushして成功した実行のログを見る

まず、cloneしたRepositoryで作業用branchを作ります。

git switch -c feature/pipelines-study

設定ファイルを保存したら、次のようにcommitしてpushします。README.mdがまだなければ、短い説明を書いたファイルをRepository直下に作成しておいてください。

git status
git add bitbucket-pipelines.yml README.md
git commit -m "Add minimal PHP pipeline"
git push -u origin feature/pipelines-study

BitbucketのRepositoryでPipelinesを開き、pushしたbranchとcommitの実行を選択します。処理が正常に終わると、結果はSuccessfulになります。

実行結果の画面でPHP environment checkのstepを選ぶと、コマンドごとのログを確認できます。

• php -v: PHPのバージョンが表示される
• test -f README.md: ファイルがあれば終了コード0で終わる。成功時のメッセージは出力されない
• echo: Pipeline completed successfully.が表示される

Successfulという結果だけでなく、どのコマンドが実行されたかまで見ておくと、次に失敗させたときの違いが分かりやすくなります。

存在しないファイルを指定して失敗させる

次に、ファイル存在確認の対象をDOES_NOT_EXIST.mdへ変更します。この名前のファイルがRepositoryにないことを確認してください。

image: php:8.3-cli

pipelines:
  default:
    - step:
        name: PHP environment check
        script:
          - php -v
          - test -f DOES_NOT_EXIST.md
          - echo "Pipeline completed successfully."

変更した設定をcommitしてpushします。

git add bitbucket-pipelines.yml
git commit -m "Check pipeline failure"
git push

この例ではtest -f DOES_NOT_EXIST.mdが終了コード1を返し、stepが失敗します。Pipelinesの標準設定ではコマンドの失敗時に処理が止まるため、その後の完了メッセージは出力されません。実行結果はFailedになります。

Pipelinesから今回のcommitの実行を開き、stepのログを確認します。PHPのバージョンは表示されている一方で、ファイル存在確認のところで止まっていることが分かります。test -f自体は、ファイルがなくても説明文を出力しないため、失敗したコマンドと終了コードを確認するのがポイントです。

今回は意図的な失敗なので、設定どおりに問題を検出できています。YAMLの書き方に問題がある場合はErrorになることもあるため、コマンドの失敗と設定ファイルの不備を分けて確認してください。

修正したcommitで再び成功することを確認する

ファイル存在確認をtest -f README.mdへ戻し、もう一度commitしてpushします。

git add bitbucket-pipelines.yml
git commit -m "Restore successful pipeline"
git push

Pipelinesで修正後のcommitの実行を選び、Successfulになっていることと、完了メッセージが出力されていることを確認します。過去の失敗結果と見比べるときも、どのbranchとcommitを確認しているかを意識しておきましょう。

実行結果の画面にはRerunもあり、同じ実行をやり直す際に使えます。今回は設定を修正した結果を確認するため、新しくpushしたcommitの実行を確認します。

この流れで、設定、push、実行結果、失敗ログ、修正後の確認までを試せます。今回のCI例が確認しているのはPHPの実行環境とファイルの存在だけです。アプリケーションの動作を確認する段階では、別途テストを用意し、その実行コマンドを組み込んでいきます。

参考資料

• Atlassian Support: Get started with Bitbucket Pipelines
• Atlassian Support: Configure your first pipeline
• Atlassian Support: Pipeline start conditions
• Atlassian Support: View your pipeline
• Atlassian Support: コマンドが失敗してもPipelinesが成功する場合の確認点