変数とシークレット

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

変数は、ビルドコンテナの環境変数として設定されています。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 のようなコマンドは動作しなくなります。

ワークスペース変数

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

プロファイルアバターからワークスペースを選択します。
上部のナビゲーションバーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウンメニューから [ワークスペース設定] を選択します。
左側のメニューで [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 をそのツールと統合して、必要に応じてそのツールからシークレットを取得できます。

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

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

サードパーティのシークレットプロバイダーが Bitbucket と通信できるようミドルウェアをコーディングします。
セルフホストランナーをご利用の場合は、サードパーティのシークレットプロバイダーに接続するように Bitbucket ランナーをセットアップします。
シークレットを取得するように 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〜3 に従って、[削除] ボタンを選択します。

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

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

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

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

プロバイダーからシークレットを取得するパイプライン・ステップごとにOICDを有効にします。
プロバイダーに保存されているシークレットの名前と一致する変数を使用してください。

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

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

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

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

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

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

コミュニティに質問