パイプラインのリファレンス変数
変数は、ビルド コンテナの環境変数として設定されています。Bitbucket-pipelines.ymlファイルか、次の方法で変数を参照して呼び出す任意のスクリプトから変数にアクセスすることができます。
1
$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 | このステップを識別する Bitbucket OIDC プロバイダーによって生成された「ID トークン」です。このトークンは、AWS や GCP などのリソース サーバーへの認証情報を使用しないアクセスに使用できます。詳細 |
BITBUCKET_SSH_KEY_FILE | Bitbucket Pipelines 非公開 SSH キーの場所。このキーを BuildKit で利用すると、SSH で外部リソースにアクセスできます。 この変数は、Bitbucket Cloud と Linux Docker Pipelines ランナー上で実行されているパイプラインでのみ利用できます。 |
ユーザー定義変数
変数は、ワークスペース、リポジトリ、およびデプロイ環境の各レベルで、追加、編集、または削除できます。既存の変数と同じ名前を使用した場合、それをオーバーライドできます。オーバーライドの順序は、デプロイメント > リポジトリ > ワークスペース > デフォルト変数です。各デプロイ環境は独立しているので、各環境で同じ変数名に別の値を使用できます。
始める前に、次の点に注意してください。
PATH という名前のパイプライン変数を構成しないでください。構成すると、すべてのパイプライン ステップが中断する可能性があります。これは、シェルがコマンドを見つけるために PATH を使用することにより発生します。したがって、通常のロケーションのリストを置き換えると、docker のようなコマンドは動作しなくなります。
ワークスペース変数
ワークスペースに指定した変数は、そのワークスペースに所属するすべてのリポジトリからアクセスできます。ワークスペースの変数を管理するには管理者である必要があります。
プロファイル アバターからワークスペースを選択します。
上部のナビゲーション バーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウン メニューから [ワークスペース設定] を選択します。
左側のメニューで [Pipelines] > [ワークスペースの変数] へ移動します。
ワークスペースの変数はリポジトリ変数で上書きすることができます。
ワークスペースの変数には、チームまたはアカウントに所属するリポジトリ (非公開または公開) への書き込み権限を持つすべてのユーザーがアクセスできます。
変数を管理するには、ワークスペースまたはリポジトリそれぞれの管理者である必要があります。
リポジトリ変数
リポジトリで書き込みアクセス権限を持つユーザーは、リポジトリ レベルに追加されたパイプライン変数を使用できます。リポジトリ変数にアクセスし、設定するには、そのリポジトリの管理者でなければなりません。
リポジトリからリポジトリ変数を管理するには、[リポジトリ設定] > [Pipelines] > [リポジトリ変数] の順に進みます。注: リポジトリ変数はチーム変数を上書きします。
デプロイ変数
特定のデプロイ環境でのみ使用されるように変数を定義できます。
リポジトリからデプロイ変数の管理もできます。[リポジトリ設定] > [Pipelines] > [デプロイ] の順に進んでください。注: デプロイ変数はチーム変数とリポジトリ変数の両方を上書きし、各環境に固有です。
1
2
3
4
5
6
7
8
9
10
11
12
13
# 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 ファイルで使用しました。
1
2
3
4
5
6
pipelines:
default:
- step:
script:
- expr 10 / $MY_HIDDEN_NUMBER
- echo $MY_HIDDEN_NUMBER
変数の値は、スクリプトで使用することはできますが、ログには公開されません。変数名 $MY_HIDDEN_NUMBER と置き換えられます。
出力の生成方法に関わらず、ログ ファイルに保護された変数の値が出力される場合、それらはすべて Pipelines によってマスクされます。
保護された変数の値を一般的な用語に設定している場合、それがログ ファイルに表示される際には必ず変数名で置き換えられます。保護された変数は一意の認証トークンやパスワードで使用するために設計されているため、クリア テキストで使用される用語と重複する可能性は考慮されていません。
また Pipelines は、URL で変数を使用する際にそれらが表示されるのを防ぐため、変数の値について、複数の基本的なエンコーディング (URL エンコーディングなど) の照合を行います。
サードパーティのシークレット プロバイダー
この機能は、セルフホスト ランナーとクラウド ランナーを使用するパイプラインで利用可能です。
組織が HashiCorp Vault などのサードパーティのシークレット管理ツールを使用してシークレットを保存または循環している場合、Bitbucket Pipelines をそのツールと統合して、必要に応じてそのツールからシークレットを取得できます。
これは高度な機能であり、サードパーティのシークレット プロバイダーに固有のミドルウェアをコーディングする必要があります。
サードパーティのシークレット プロバイダーを使用するには、次の手順に従います。
サードパーティのシークレット プロバイダーが Bitbucket と通信できるようミドルウェアをコーディングします。
セルフホスト ランナーをご利用の場合は、サードパーティのシークレット プロバイダーに接続するように Bitbucket ランナーをセットアップします。
シークレットを取得するように Bitbucket パイプラインをセットアップします。
1. ミドルウェアのコーディング
すぐに始められるように、サンプル リポジトリをご用意しました。このリポジトリには、サードパーティのシークレット プロバイダー統合用の Java アプリの例が含まれています。
このアプリは次のことを行います。
この例を出発点として使用して、サードパーティプロバイダーに固有の独自のミドルウェアをコーディングします。
ミドルウェアをコーディングするときは、必ず次のことを行ってください。
シークレット プロバイダーを使用すると、Bitbucket の外部でシークレットを保存/管理できます。シークレット プロバイダーを追加するには、ワークスペースの管理者である必要があります。
セルフホスト ランナー
自社ホスト ランナーは、起動時にサードパーティのシークレット プロバイダーに接続する必要があります。これを行うには、プロバイダー用に記述したミドルウェアの URI を指定する必要があります。さまざまな種類の自社ホスト ランナーでこれを行う方法は次のとおりです。
Docker
コンテナを起動するときにSECRET_PROVIDER_URI環境変数を設定します。
1
docker container run ... -e SECRET_PROVIDER_URI="http://secret.provider/endpoint" ...
シェル
start.shスクリプトを呼び出すときに--secretProviderUriプロパティを追加します
1
./start.sh ... --secretProviderUri "http://secret.provider/endpoint" ...
Powershell
start.ps1スクリプトを呼び出すときに-secretProviderUriプロパティを追加します
1
.\start ... -secretProviderUri "http://secret.provider/endpoint" ..
クラウド ランナー
上部のナビゲーション バーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウン メニューから [ワークスペース設定] を選択します。
左側のサイドバーの [パイプライン] で [ワークスペース変数] を選択します。
提供されたフィールドに、シークレット プロバイダーのエンドポイントを追加します。
[追加] ボタンを選択して、シークレット プロバイダーのエンドポイントを追加します。
シークレット プロバイダーを削除するには、上記のステップ 1〜3 に従って、[削除] ボタンを選択します。
シークレット プロバイダーを更新する
シークレット プロバイダーを更新するには、上記のステップ 1〜3 に従い、[削除] ボタンを選択して現在のシークレット プロバイダーを削除し、上記のステップ 4〜5 に従って新しいプロバイダーを追加します。
3. Bitbucket パイプラインのセットアップ
サードパーティのシークレット プロバイダーからシークレットを取得するには、次の手順に従います。
パイプラインは、その変数の現在の値を、プロバイダーでホストされているシークレットに自動的に置き換えます。
ミドルウェアが Bitbucket に送信できるデータをフィルタリングする際に、取得するシークレットがすべてプロビジョニングされていることを確認します。
たとえば、パイプラインに値 1234 の $SECRET という変数が含まれていて、サードパーティのシークレット プロバイダーに同じ名前の対応するシークレットが含まれている場合、パイプラインは実行時に 1234 を適切なシークレット値に置き換えます。
