変数とシークレット

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

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

$AWS_SECRET

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

セルフホスト型の Windows ランナーを使用している場合は、次の方法で変数にアクセスできます。

$env: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 ランナー上で実行されているパイプラインでのみ利用できます。
BITBUCKET_STEP_RUN_NUMBER	現在のステップの実行番号を指定します。これは、最初の実行の 1 から始まり、特定のステップが実行された回数を識別するのに役立ちます。

ユーザー定義変数

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

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

名前には ASCII 文字、数字、およびアンダースコアのみを含めることができます。
名前では大文字と小文字が区別されます。
名前の先頭を数字にすることはできません。
シェルで定義された変数は使用しないでください。コマンド printenv のステップを使用してそれらを見つけることができます。
カスタム変数の値には 120,000 文字の制限があります。

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

ワークスペース変数

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

プロファイルアバターからワークスペースを選択します。
上部のナビゲーションバーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウンメニューから [ワークスペース設定] を選択します。
左側のメニューで [Pipelines] > [ワークスペースの変数] へ移動します。

ワークスペースの変数はリポジトリ変数で上書きすることができます。
ワークスペースの変数には、チームまたはアカウントに所属するリポジトリ (非公開または公開) への書き込み権限を持つすべてのユーザーがアクセスできます。
変数を管理するには、ワークスペースまたはリポジトリそれぞれの管理者である必要があります。

リポジトリ変数

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

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

共有パイプライン変数

あるステップから変数を共有して、同じパイプラインの後続のステップからアクセスできるようにすることができます。

考慮事項

変数の値は、後のステップのビルド設定セクションにプレーンテキストで記録されます。この機能は、セキュアな変数での使用を目的としたものではありません。
変数名は、ステップ yml の output-variables オプションで定義する必要があります。
共有変数はパイプラインあたり 50 個に制限されます。
すべての共有パイプライン変数には 100 KB のサイズ制限があります (変数キー + 値が計算に含まれます)。
- この機能は、大量のデータを共有することを目的としたものではなく、それ以外のもの (アーティファクトなど) を使用する方が適しています。
以前にセキュアとマークされた共有変数を検出してブロックします。
- この方法を使用してセキュアな変数を共有しようとすると、エクスポートされた値は「UNSUPPORTED_SECURE_VARIABLE」の値に置き換えられます。
並列ステップのグループ内では、変数名は一意である必要があります。
共有パイプライン変数は、パイプラインのライフサイクル全体にわたって存続します。これは、障害が再実行されたときにも利用できることを意味します。パイプライン全体を再実行すると、新しいパイプラインが作成され、元のパイプラインからエクスポートされた変数は利用できなくなります。

例 - あるステップから変数をエクスポートし、それを次のステップで使用する

step:
  script:
  	- echo "VARIABLE_NAME=my-value" >> $BITBUCKET_PIPELINES_VARIABLES_PATH
  output-variables:
    - VARIABLE_NAME
step:
  script:
    - echo $VARIABLE_NAME

例 – Windows ランナー

step:
  script:
    - Add-Content -Path $Env:BITBUCKET_PIPELINES_VARIABLES_PATH -Value "VARIABLE_NAME=my-value"
  output-variables:
    - VARIABLE_NAME
step:
  script:
    - echo $Env:VARIABLE_NAME

デプロイ変数

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

リポジトリからデプロイ変数の管理もできます。[リポジトリ設定] > [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 エンコーディングなど) の照合を行います。

パイプライン YAML ファイルで変数を使用する

制限事項とその他の重要な情報

特定のタイプの変数では、.yaml へのテンプレート化をサポートしていません。

保護された変数: これらの値がログに表示されないようにする必要があるため、サポートされていません。
カスタムパイプライン変数: これらの値は .yaml ファイルの解析後に定義されるため、サポートされていません。
特定の既定の変数: これらの値は .yaml ファイルの解析後に定義されるため、サポートされていません。

ワークフローで動的なパイプラインを使用している場合、動的パイプラインの実行前に変数が .yaml に挿入されることにご注意ください。つまり、両方の機能に相互に完全な互換性があるということです。

変数は、シンプルで標準化されたテンプレート構文を使用して .yaml ファイルにテンプレート化できます。.yaml に挿入する必要がある変数のキーを ${{ }} タグで囲むだけで、その変数の値が実行時に挿入されます。

使用する変数は、ワークスペース設定またはリポジトリ設定のいずれかで事前に設定されている必要があります。変数を参照して作成する方法については、このヘルプドキュメントの「参照変数」または「ワークスペース変数とリポジトリ変数」セクションを参照してください。

現時点では、YAML ファイルをテンプレート化する場合、ワークスペース、リポジトリ変数、および特定の既定の変数 (以下のリストを参照) のみを使用できます。セキュリティ上の理由から、セキュア変数はサポートされていません。
- CI
- BITBUCKET_WORKSPACE
- BITBUCKET_REPO_SLUG
- BITBUCKET_REPO_UUID
- BITBUCKET_REPO_FULL_NAME
- BITBUCKET_REPO_IS_PRIVATE
- BITBUCKET_REPO_OWNER
- BITBUCKET_REPO_OWNER_UUID
- BITBUCKET_GIT_HTTP_ORIGIN
- BITBUCKET_GIT_SSH_ORIGIN
- BITBUCKET_PROJECT_KEY
- BITBUCKET_PROJECT_UUID
- BITBUCKET_COMMIT
- BITBUCKET_BRANCH
- BITBUCKET_TAG
- BITBUCKET_PR_ID
- BITBUCKET_PR_DESTINATION_BRANCH
- BITBUCKET_PR_DESTINATION_COMMIT

詳細な例:

次の例では、パイプラインの YAML ファイルには次の変数が含まれています。

Example account variable: IMAGE_NAME = atlassian/default-image:3
Example repository variable: CACHE_PATH = yaml-templating-cache
Example default variable: BITBUCKET_REPO_SLUG = example-repo

パイプラインの YAML (テンプレート構文付き)

image: ${{IMAGE_NAME}}
definitions:
  caches:
    test-cache: ${{CACHE_PATH}}
pipelines:
  default:
    - step:
        name: 'Pipeline Step in ${{BITBUCKET_REPO_SLUG}}'
        caches:
          - test-cache
        script:
          - echo "Hello! test cache" >> $CACHE_PATH/test.txt

変数追加後の YAML コンテンツ

image: atlassian/default-image:3
definitions:
  caches:
    test-cache: yaml-templating-cache
pipelines:
  default:
    - step:
        name: 'Pipeline Step in example-repo'
        caches:
          - test-cache
        script:
          - echo "Hello! test cache" >> $CACHE_PATH/test.txt

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

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

組織が 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 を適切なシークレット値に置き換えます。

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

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

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

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

コミュニティに質問