ドキュメント
無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

Bitbucket との連携

1+ year ago1 min read
クラウド
このページの内容

概要

CircleCI で Bitbucket を使用するには、Bitbucket アカウントを接続する必要があります。 プロジェクトを CircleCI に追加すると、ユーザー登録時に CircleCI に与えた権限に基づいて、以下の設定がリポジトリに追加されます。

  • デプロイキー: Bitbucket からプロジェクトをチェックアウトするために使用されます。

  • サービスフック (またはプッシュフック): Bitbucket にプッシュしたときに CircleCI に通知を送信するために使用されます。

CircleCI のデフォルトでは、プッシュフックでビルドが行われます。 したがって、リポジトリのすべてのプッシュフックに対してビルドがトリガーされます。また、プッシュはビルドをトリガーする最も一般的なケースです。

あまり一般的ではありませんが、CircleCI は以下の場合にもフックを使用します。

  • PR フック (プルリクエストフック) を処理して、CircleCI アプリの PR 情報を保存します。 CircleCI で Only build pull requests 設定が有効になっていると、PR がオープンされたとき、または既存の PR が存在するブランチへのプッシュがあったときにのみ、ビルドをトリガーします。 これが設定されている場合でも、プロジェクトのデフォルトブランチへのすべてのプッシュは、常にビルドされます。

  • CircleCI で Build forked pull requests 設定が有効になっている場合、フォークされたリポジトリから作成された PR に応答してビルドをトリガーします。

これらの設定は、CircleCI Web アプリの各プロジェクトの Project Settings セクションでご確認いただけます。

Only Build Pull Requests 設定をオーバーライドする機能もサポートされています。 具体的には、CircleCI は正規表現 (例: release.\*) で指定されたデフォルト以外のブランチからのすべてのコミットに対して検証を実行します。

現時点では、 Only Build Pull Requests 設定をオーバーライドする唯一の方法は、 https://support.circleci.com/ でサポートリクエストをオープンすることです。 このリクエストには、CircleCI がすべてのコミットを検証するブランチの 許可リスト に追加したい正規表現を記載してください。 組織に適用されている正規表現の削除や編集をする際もサポートリクエストを提出する必要があります。 詳細については、 Ideas を参照してください。

Bitbucket で Webhook を編集して、ビルドをトリガーするイベントを制限できます。 Webhook の設定を編集することで、CircleCI に送信されるフックを変更できますが、ビルドをトリガーするフックの種類は変更されません。 CircleCI は常にプッシュフックでビルドを行い、設定によっては PR フックでもビルドを行います。ただし、Webhook の設定からプッシュフックを削除すると、ビルドを行いません。

詳しくは Atlassian が提供する Webhook 管理に関するドキュメント を参照してください。

タグプッシュでのビルド方法については、CircleCI のドキュメントで ワークフローフィルター の説明を参照してください。

アクセス許可の概要

CircleCI では、 Bitbucket のアクセス許可モデル に定義されているように、Bitbucket からの次のアクセス許可をリクエストします。

読み取りアクセス許可

  • ユーザーのメールアドレスを取得する

書き込みアクセス許可

  • ユーザーのリポジトリリストを取得する

  • ユーザーアカウントに SSH キーを追加する

管理者アクセス許可 (プロジェクトの設定に必要)

  • リポジトリにデプロイキーを追加する

  • リポジトリにサービスフックを追加する

CircleCI が使用するアクセス許可の数をどうしても減らしたい場合は Bitbucket に連絡し、その旨をお伝えください。

Bitbucket アカウントの接続

CircleCI Web アプリで、Bitbucket に接続する組織を選択し、サイドバーの下部にあるユーザーアイコンをクリックして User Settings に移動します。 ここで Bitbucket を選択できます。 接続すると、既存のプロジェクトがダッシュボードに挿入され、フォローするプロジェクトを選択できるようになります。

次に、CircleCI でプロジェクトを実行するために必要なアクセス許可を設定します。

デプロイキーとユーザーキー

デプロイキーとは

新しいプロジェクトを追加すると、CircleCI は Bitbucket 上にそのプロジェクト用のデプロイキーを作成します。 デプロイキーは SSH キーペアで、1 つはパブリック、もう 1 つはプライベートです。 Bitbucket がパブリックキーを格納し、CircleCI がプライベートキーを格納します。 デプロイキーは、CircleCI に単一のリポジトリへのアクセス権を提供します。 CircleCI によるリポジトリへのプッシュを防止するには、このデプロイキーを読み取り専用に設定します。

ユーザーキーとは

ユーザーキーは、ユーザーに固有の SSH キーペアです。 Bitbucket がパブリックキーを格納し、CircleCI がプライベートキーを格納します。 プライベートキーを持っていると、プロジェクトへの「Git」アクセスの目的で、そのユーザーとして行動することができます。

現在、Bitbucket は、ユーザーキーを作成する API を CircleCI に提供していません。 しかし、以下のセクションで説明する回避策によりユーザーキーを作成することができます。

Bitbucket ユーザーキーの作成

  1. CircleCI アプリケーションで、プロジェクトの設定に移動します。

  2. SSH Keys ページに移動し、User Key セクションまでスクロールダウンします。

  3. Add User Key ボタンを右クリックし、Inspect オプションを選択して、ブラウザーの検証ツールを起動します。

  4. ブラウザーの検証ツールで、Network タブを選択し、コンソールをクリアします。

  5. Add User Key をクリックし、Confirm User をクリックして、このモーダルでユーザーがマシンユーザーであることを確認します。 必須ではありませんが、マシンユーザーを作成することを強く推奨します。

  6. フィルターボックスで、checkout と入力します。 こうすることで、checkout-key を見つけやすくなります。 201 ステータスの checkout-key をクリックして Preview タブを選択します。 public_key を引用符を含めずにクリップボードにコピーします。

  7. Bitbucket の SSH キーの設定方法 の説明に従って、Bitbucket にキーを追加します。

この SSH ユーザーキーには "PREFERRED" のラベルが表示されます。 プロジェクトにデプロイキーも付与されている場合は、SSH ユーザーキーが優先的に使用されます。

Bitbucket SSHキーの追加作成

他のサービスにアクセスするために追加のSSHキーが必要な場合は、以下の手順で追加のキーを作成することができます。

この例では、GitHub リポジトリは https://bitbucket.org/you/test-repo/src/main で、CircleCI プロジェクトは https://app.circleci.com/pipelines/bitbucket/you/test-repo です。

  1. Bitbucket の説明 に従って、SSH キーペアを作成します。 パスワードを入力するよう求められた場合、入力しないでください（以下はmacOSでキーを生成するコマンドの一例です）。

      ssh-keygen -t ed25519 -C "your_email@example.com"

  2. https://bitbucket.org/you/test-repo/admin/access-keys に移動して Add Deploy Key をクリックします。 Label フィールドに label を入力し、手順 1 で作成したパブリックキーをコピー＆ペーストします。 次に Add SSH Key をクリックします。

  3. CircleCI アプリのプロジェクトの設定にアクセスし、SSH Keys と Add SSH key を選択します。 Hostname のフィールドには、bitbucket.com を入力し、手順 1 で作成したプライベートキーを追加します。 次に Add SSH Key をクリックします。

  4. .circleci/config.yml ファイルで、add_ssh_keys キーを使用してジョブにフィンガープリントを追加します。

      version: 2.1

  jobs:
    deploy-job:
      steps:
        - add_ssh_keys:
            fingerprints:
              - "SO:ME:FIN:G:ER:PR:IN:T"

ジョブから BitBucket リポジトリにプッシュすると、CircleCI は追加された SSH キーを使用します。

プライベートキーの使用方法

CircleCI がプロジェクトをビルドするときには、プライベートキーが .ssh ディレクトリにインストールされ、それに続いて SSH がバージョン管理プロバイダーと通信するように設定されます。 したがって、プライベートキーは以下の用途で使用されます。

  • メインプロジェクトのチェックアウト

  • Bitbucket でホスティングされるサブモジュールのチェックアウト

  • Bitbucket でホスティングされるプライベートな依存関係のチェックアウト

  • Git の自動マージ、タグ付けなど

プライベートキーは、 追加のプライベートリポジトリをプロジェクトでチェックアウトできるようにするため にも使用されます。

ユーザーキーのセキュリティ

CircleCI が SSH キーを公開することはありません。

CircleCI が生成するチェックアウトキーペアのプライベートキーが CircleCI システムの外に出ることはなく (パブリックキーのみ Bitbucket に転送されます)、ストレージ上では安全に暗号化されています。 しかし、これらのキーはビルドコンテナにインストールされるため、CircleCI で実行されるすべてのコードから読み取ることができます。 同様に、SSH 接続が可能な開発者は、このキーに直接アクセスできます。

SSH キーは信頼するユーザーとのみ共有してください。 ユーザーキーを使用するプロジェクトの場合、すべての Bitbucket コラボレーターがリポジトリにアクセスできるため、ユーザーキーはソースコードを委ねられる人とのみ共有してください。

ユーザーキーの追加が必要なときに表示される一般的なエラーを示します。

Python: pip install ステップの場合:

ERROR: Repository not found.

Ruby: bundle install ステップの場合:

Permission denied (publickey).

.circleci/config.yml ファイルの追加

必要なアクセス許可のセットアップが完了したら、次のステップでは、CircleCI で使用するプロジェクトに .circleci/config.yml ファイルを追加します。 CircleCI に接続するリポジトリに .circleci ディレクトリを追加してください。 そのディレクトリ内に config.yml ファイルを追加します。

.circleci/config.yml ファイルを作成し、Bitbucket のリポジトリに対してコミットすると、CircleCI は直ちにそのコードをチェックアウトし、設定されているテストがあればそれを含めて、最初のジョブを実行します。

CircleCI は、毎回クリーンなコンテナでテストを実行します。これにより、コードをプッシュするたびにテストが新たに実行され、他のユーザーはコードにアクセスできません。 テストの更新を お客様のダッシュボード でリアルタイムに確認します。 ステータス更新をメール通知で受け取ったり、Bitbucket に表示されるステータスバッジを確認したりできます。 また、プルリクエスト画面にもすべてのテストが合格したことを示す総合的なステータスが表示されます。

順を追って設定を確認するには、 設定ファイルのチュートリアル を参照してください。

プロジェクトでの追加のプライベートリポジトリのチェックアウトの有効化

テストプロセスが複数のリポジトリを参照する場合、CircleCI ではデプロイキーに加えて Bitbucket ユーザーキーも必要となります。デプロイキーは _1 つ_のリポジトリに対してのみ有効であるのに対して、Bitbucket ユーザーキーはユーザーの_すべて_の Bitbucket リポジトリに対してアクセス権を持つためです。

プロジェクトの Project Settings > SSH keys で、CircleCI に渡す Bitbucket のユーザーキーを指定します。 ページの User Key までスクロールダウンし、Authorize with Bitbucket をクリックします。 CircleCI は、この新しい SSH キーを作成し、それを Bitbucket のユーザーアカウントに関連付けて、ユーザーのすべてのリポジトリにアクセスできるようにします。

キーのベストプラクティス

  • 可能な限り、デプロイキーを使用します。

  • リポジトリへのユーザーアクセスを取り消す場合、デプロイキーまたはユーザーキーを交換する必要があります。

    1. Bitbucket へのユーザーアクセスを取り消した後、Bitbucket でキーを削除します。

    2. CircleCI プロジェクトでキーを削除します。

    3. CircleCI プロジェクトでキーを再生成します。

  • 開発者に付与されている以上のアクセス権を必要とするリポジトリのビルドに、開発者がユーザーキーを使用してアクセスできないようにします。

SSH ホストの信頼性の確立

SSH キーを使用してリポジトリをチェックアウトするとき、既知のホストファイル (~/.ssh/known_hosts) に Bitbucket のフィンガープリントの追加が必要になる場合があります。そうすることで、Executor は接続しているホストの信頼性を検証できます。 これは checkout ジョブステップによって自動的に処理されます。カスタマイズされたチェックアウトコマンドを使用する場合は、以下のコマンドを実行する必要があります。

mkdir -p ~/.ssh

echo 'bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==
' >> ~/.ssh/known_hosts

対象サーバーの SSH キーは ssh-keyscan <host> を実行することで取得できます。そして、取得されたキーのうち ssh-rsa プレフィックスがついているものをジョブの known_hosts ファイルに追加します。 たとえば、以下のようになります。

➜  ~ ssh-keyscan bitbucket.com
# bitbucket.com:22 SSH-2.0-babeld-2e9d163d
bitbucket.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
# bitbucket.com:22 SSH-2.0-babeld-2e9d163d
# bitbucket.com:22 SSH-2.0-babeld-2e9d163d
➜  ~ ✗

以下のコマンドを実行すると、キーを known_hosts に追加できます。

ssh-keyscan bitbucket.com >> ~/.ssh/known_hosts

組織名とリポジトリ名の変更

組織名やリポジトリ名を変更したい場合は、 組織名およびリポジトリ名の変更ガイドに従い、変更プロセスの間に環境変数やコンテキストへのアクセスを失わないようにしてください。

次のステップ

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site