変数とシークレット

パイプラインのリファレンス変数

変数は、ビルド コンテナの環境変数として設定されています。Bitbucket-pipelines.ymlファイルか、次の方法で変数を参照して呼び出す任意のスクリプトから変数にアクセスすることができます。 

$AWS_SECRET

ここで AWS_SECRET は変数の名前です。

デフォルトの変数

Bitbucket Pipelines は、ビルドで利用でき、スクリプトでも使用可能な一連の既定の変数を提供します。

同じ名前の変数を指定してデフォルトの変数をオーバーライドすることができます。

既定の変数

説明

CI

既定値は true です。パイプラインが実行されるたびに設定されます。

BITBUCKET_BUILD_NUMBER

ビルドの一意の識別子。ビルドごとに増え、一意のアーティファクト名の作成に使用できます。

BITBUCKET_CLONE_DIR

Docker コンテナ内でのリポジトリのクローン先のディレクトリの絶対パス。

BITBUCKET_COMMIT

ビルドを開始したコミットのコミット ハッシュ値。

BITBUCKET_WORKSPACE

リポジトリが所属するワークスペースの名前。

BITBUCKET_REPO_SLUG

リポジトリ名の URL 用の名前。詳細については、「スラッグとは」を参照してください。

BITBUCKET_REPO_UUID

リポジトリの UUID。

BITBUCKET_REPO_FULL_NAME

リポジトリの完全な名前 (http://bitbucket.org/ に続くすべての文字)。

BITBUCKET_BRANCH

ソース ブランチ。この値はブランチ上でのみ利用可能です。

タグのビルドでは使用できません。

BITBUCKET_TAG

ビルドを開始したコミットのタグ。この値はタグでのみ使用できます。

ブランチのビルドでは使用できません。

BITBUCKET_BOOKMARK

Mercurial プロジェクトで使用します。

BITBUCKET_PARALLEL_STEP

グループ内の現在のステップのゼロベース インデックス。例: 0、1、2、...

並行ステップでのみ使用できます。

BITBUCKET_PARALLEL_STEP_COUNT

グループ内のステップの合計数。例: 5。

並行ステップでのみ使用できます。

BITBUCKET_PR_ID

プル リクエスト ID
プル リクエストでトリガーされたビルドでのみ利用可能です。

BITBUCKET_PR_DESTINATION_BRANCH

プル リクエストの宛先ブランチ (BITBUCKET_BRANCH と組み合わせて使用)

プル リクエストでトリガーされたビルドでのみ利用可能です。

BITBUCKET_GIT_HTTP_ORIGIN

オリジンの URL。例: http://bitbucket.org/<workspace>/<repo>

BITBUCKET_GIT_SSH_ORIGIN

SSH オリジン。例: git@bitbucket.org:/<workspace>/<repo>.git

BITBUCKET_EXIT_CODE

ステップの終了コードは after-script セクションで使用できます。値は 0 (成功) または 1 (失敗) になります。

BITBUCKET_STEP_UUID

ステップの UUID。

BITBUCKET_PIPELINE_UUID

 パイプラインの UUID。

BITBUCKET_DEPLOYMENT_ENVIRONMENT

環境名の URL フレンドリーなバージョン。

BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID

REST API 経由で環境にアクセスするための環境の UUID。

BITBUCKET_PROJECT_KEY

現在のパイプラインが属するプロジェクトのキー。

BITBUCKET_PROJECT_UUID

現在のパイプラインが属するプロジェクトの UUID。

BITBUCKET_STEP_TRIGGERER_UUID

(プッシュ、マージなどを実行することによって) ビルドを開始したユーザー、およびスケジュールされたビルドの場合は、パイプライン ユーザーの UUID。

BITBUCKET_STEP_OIDC_TOKEN

The 'ID Token' generated by the Bitbucket OIDC provider that identifies the step. This token can be used to access resource servers, such as AWS and GCP without using credentials. Learn more

BITBUCKET_SSH_KEY_FILE

The location of the Bitbucket Pipelines private SSH key. This key can be used with BuildKit to access external resources using SSH.

この変数は、Bitbucket Cloud と Linux Docker Pipelines ランナー上で実行されているパイプラインでのみ利用できます。

 

ユーザー定義変数

変数は、ワークスペース、リポジトリ、およびデプロイ環境の各レベルで、追加、編集、または削除できます。既存の変数と同じ名前を使用した場合、それをオーバーライドできます。オーバーライドの順序は、デプロイメント > リポジトリ > ワークスペース > デフォルト変数です。各デプロイ環境は独立しているので、各環境で同じ変数名に別の値を使用できます。

始める前に、次の点に注意してください。

  • 名前には ASCII 文字、数字、およびアンダースコアのみを含めることができます。

  • 名前では大文字と小文字が区別されます。

  • 名前の先頭を数字にすることはできません。

  • シェルで定義された変数は使用しないでください。コマンド printenv のステップを使用してそれらを見つけることができます。

PATH という名前のパイプライン変数を構成しないでください。構成すると、すべてのパイプライン ステップが中断する可能性があります。これは、シェルがコマンドを見つけるために PATH を使用することにより発生します。したがって、通常のロケーションのリストを置き換えると、docker のようなコマンドは動作しなくなります。

ワークスペース変数

ワークスペースに指定した変数は、そのワークスペースに所属するすべてのリポジトリからアクセスできます。ワークスペースの変数を管理するには管理者である必要があります。

  1. プロファイル アバターからワークスペースを選択します。

  2. 上部のナビゲーション バーにある [設定] (歯車アイコン ) を選択します。

  3. [設定] ドロップダウン メニューから [ワークスペース設定] を選択します。

  4. 左側のメニューで [Pipelines] > [ワークスペースの変数] へ移動します。

  • ワークスペースの変数はリポジトリ変数で上書きすることができます。

  • ワークスペースの変数には、チームまたはアカウントに所属するリポジトリ (非公開または公開) への書き込み権限を持つすべてのユーザーがアクセスできます。

  • 変数を管理するには、ワークスペースまたはリポジトリそれぞれの管理者である必要があります。

リポジトリ変数

リポジトリで書き込みアクセス権限を持つユーザーは、リポジトリ レベルに追加されたパイプライン変数を使用できます。リポジトリ変数にアクセスし、設定するには、そのリポジトリの管理者でなければなりません。

リポジトリからリポジトリ変数を管理するには、[リポジトリ設定] > [Pipelines] > [リポジトリ変数] の順に進みます。注: リポジトリ変数はチーム変数を上書きします。

デプロイ変数

特定のデプロイ環境でのみ使用されるように変数を定義できます。

リポジトリからデプロイ変数の管理もできます。[リポジトリ設定] > [Pipelines] > [デプロイ] の順に進んでください。注: デプロイ変数はチーム変数とリポジトリ変数の両方を上書きし、各環境に固有です。

 

# Deployment variables will only work within deployment steps in bitbucket-pipelines.yaml image: atlassian/default-image:2 pipelines: default: - step: script: - <script> - step: name: Deploy to Test deployment: Test script: - echo $DEPLOYMENT_VARIABLE

保護された変数

変数は保護することができます。保護した変数はスクリプトで使用できますが、その値はビルド ログでは非表示になります (以下の例を参照してください)。保護された変数を編集したい場合、新しい値を指定するか削除する必要があります。保護された変数は、暗号化された値として保存されます。変数を保護するには、南京錠のアイコンをクリックします。

パドロックは値と追加の間で強調表示されます

保護された変数のマスキング

Pipelines は、ビルド ログを表示するチーム メンバーに公開されることがないよう、保護された変数をマスクします。セキュアな変数と一致する値がログに表示された場合、Pipelines はその値を $VARIABLE_NAME と置き換えます。

これにより、保護された変数が正常に機能しているかどうかが一見してわかりづらくなる可能性があります。次のような例で説明します。

最初に、5 の値を持つ保護された変数 MY_HIDDEN_NUMBER を作成します。

保護された変数のマスキング

次に、この変数を YAML ファイルで使用しました。

 

pipelines: default: - step: script: - expr 10 / $MY_HIDDEN_NUMBER - echo $MY_HIDDEN_NUMBER

変数の値は、スクリプトで使用することはできますが、ログには公開されません。変数名 $MY_HIDDEN_NUMBER と置き換えられます。

ビルド ログの例

出力の生成方法に関わらず、ログ ファイルに保護された変数の値が出力される場合、それらはすべて Pipelines によってマスクされます。

保護された変数の値を一般的な用語に設定している場合、それがログ ファイルに表示される際には必ず変数名で置き換えられます。保護された変数は一意の認証トークンやパスワードで使用するために設計されているため、クリア テキストで使用される用語と重複する可能性は考慮されていません。

また Pipelines は、URL で変数を使用する際にそれらが表示されるのを防ぐため、変数の値について、複数の基本的なエンコーディング (URL エンコーディングなど) の照合を行います。

サードパーティのシークレット プロバイダー

この機能は、セルフホスト ランナーとクラウド ランナーを使用するパイプラインで利用可能です。

組織が HashiCorp Vault などのサードパーティのシークレット管理ツールを使用してシークレットを保存または循環している場合、Bitbucket Pipelines をそのツールと統合して、必要に応じてそのツールからシークレットを取得できます。

これは高度な機能であり、サードパーティのシークレット プロバイダーに固有のミドルウェアをコーディングする必要があります。

サードパーティのシークレット プロバイダーを使用するには、次の手順に従います。

  1. サードパーティのシークレット プロバイダーが Bitbucket と通信できるようミドルウェアをコーディングします。

  2. セルフホスト ランナーをご利用の場合は、サードパーティのシークレット プロバイダーに接続するように Bitbucket ランナーをセットアップします。

  3. シークレットを取得するように Bitbucket パイプラインをセットアップします。

1. ミドルウェアのコーディング

すぐに始められるように、サンプル リポジトリが提供されています。このリポジトリには、サードパーティのシークレット プロバイダー統合用の Java アプリの例が含まれています。

このアプリは次のことを行います。

  • プロバイダーが Bitbucket からのシークレット リクエストに応答できるようにします。

  • リクエストが OIDC JWT トークンを使用して Bitbucket から送信されていることを検証します。

  • シークレットの基本的なセットを返します。

この例を出発点として使用して、サードパーティプロバイダーに固有の独自のミドルウェアをコーディングします。

ミドルウェアをコーディングするときは、必ず次のことを行ってください。

  • サンプル リポジトリで提供されている Open API 仕様を使用して、ミドルウェアが Bitbucket と通信できることを確認してください。

  • サードパーティ プロバイダー統合で Bitbucket に送信するシークレットを指定します。シークレットをフィルタリングする方法の例については、サンプル リポジトリのファイル SecretStoreImpl.java をご参照ください。

2. シークレット プロバイダーのエンドポイントを使用するようにランナーを設定する

シークレット プロバイダーを使用すると、Bitbucket の外部でシークレットを保存/管理できます。シークレット プロバイダーを追加するには、ワークスペースの管理者である必要があります。

セルフホスト ランナー

自社ホスト ランナーは、起動時にサードパーティのシークレット プロバイダーに接続する必要があります。これを行うには、プロバイダー用に記述したミドルウェアの URI を指定する必要があります。さまざまな種類の自社ホスト ランナーでこれを行う方法は次のとおりです。

Docker

コンテナを起動するときにSECRET_PROVIDER_URI環境変数を設定します。

docker container run ... -e SECRET_PROVIDER_URI="http://secret.provider/endpoint" ...
シェル

start.shスクリプトを呼び出すときに--secretProviderUriプロパティを追加します

./start.sh ... --secretProviderUri "http://secret.provider/endpoint" ...
Powershell

start.ps1スクリプトを呼び出すときに-secretProviderUriプロパティを追加します

.\start ... -secretProviderUri "http://secret.provider/endpoint" ..

クラウド ランナー

  1. 上部のナビゲーション バーにある [設定] (歯車アイコン ) を選択します。

  2. [設定] ドロップダウン メニューから [ワークスペース設定] を選択します。

  3. 左側のサイドバーの [パイプライン] で [ワークスペース変数] を選択します。

  4. 提供されたフィールドに、シークレット プロバイダーのエンドポイントを追加します。

  5. [追加] ボタンを選択して、シークレット プロバイダーのエンドポイントを追加します。

シークレット プロバイダーを削除するには、上記のステップ 1〜3 に従って、[削除] ボタンを選択します。

シークレット プロバイダーを更新する

シークレット プロバイダーを更新するには、上記のステップ 1〜3 に従い、[削除] ボタンを選択して現在のシークレット プロバイダーを削除し、上記のステップ 4〜5 に従って新しいプロバイダーを追加します。

3. Bitbucket パイプラインのセットアップ

サードパーティのシークレット プロバイダーからシークレットを取得するには、次の手順に従います。

パイプラインは、その変数の現在の値を、プロバイダーでホストされているシークレットに自動的に置き換えます。

ミドルウェアが Bitbucket に送信できるデータをフィルタリングする際に、取得するシークレットがすべてプロビジョニングされていることを確認します。

たとえば、パイプラインに値 1234$SECRET という変数が含まれていて、サードパーティのシークレット プロバイダーに同じ名前の対応するシークレットが含まれている場合、パイプラインは実行時に 1234 を適切なシークレット値に置き換えます。

    さらにヘルプが必要ですか?

    アトラシアン コミュニティをご利用ください。