変数とシークレット

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

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

$AWS_SECRET

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

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

$env:AWS_SECRET

デフォルトの変数

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

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

既定の変数	説明	Available on
CI	既定値は `true` です。パイプラインが実行されるたびに設定されます。	All pipelines
BITBUCKET_BUILD_NUMBER	ビルドの一意の識別子。ビルドごとに増え、一意のアーティファクト名の作成に使用できます。	All pipelines
BITBUCKET_CLONE_DIR	Docker コンテナ内でのリポジトリのクローン先のディレクトリの絶対パス。	All pipelines
BITBUCKET_COMMIT	ビルドを開始したコミットのコミットハッシュ値。	All pipelines
BITBUCKET_WORKSPACE	リポジトリが所属するワークスペースの名前。	All pipelines
BITBUCKET_WORKSPACE_UUID	The UUID of the workspace.	All pipelines.
BITBUCKET_REPO_OWNER	非推奨。 `BITBUCKET_WORKSPACE` を参照してください。	All pipelines.
BITBUCKET_REPO_OWNER_UUID	非推奨。 `BITBUCKET_WORKSPACE_UUID` を参照してください。	All pipelines.
BITBUCKET_REPO_SLUG	The URL-friendly version of a repository name. For more information, see What is a slug?	All pipelines
BITBUCKET_REPO_UUID	リポジトリの UUID。	All pipelines
BITBUCKET_REPO_FULL_NAME	リポジトリの完全な名前 (http://bitbucket.org/ に続くすべての文字)。	All pipelines
BITBUCKET_REPO_IS_PRIVATE	True if the repository is private, false otherwise.	All pipelines.
BITBUCKET_BRANCH	ソースブランチ。この値はブランチ上でのみ利用可能です。タグのビルドでは使用できません。	Only on pipelines targeting a branch
BITBUCKET_TAG	ビルドを開始したコミットのタグ。この値はタグでのみ使用できます。ブランチのビルドでは使用できません。	Only on pipelines targeting a branch
BITBUCKET_BOOKMARK	Mercurial プロジェクトで使用します。	Only on pipelines targeting a bookmark
BITBUCKET_PARALLEL_STEP	グループ内の現在のステップのゼロベースインデックス。例: 0、1、2、... 並行ステップでのみ使用できます。	Only on steps within a parallel section
BITBUCKET_PARALLEL_STEP_COUNT	グループ内のステップの合計数。例: 5。並行ステップでのみ使用できます。	Only on steps within a parallel section
BITBUCKET_PR_ID	The pull request ID Only available on a pull request triggered build.	Only on pipelines targeting a pull request
BITBUCKET_PR_DESTINATION_BRANCH	プルリクエストの宛先ブランチ (`BITBUCKET_BRANCH` と組み合わせて使用) プルリクエストでトリガーされたビルドでのみ利用可能です。	Only on pipelines targeting a pull request
BITBUCKET_PR_DESTINATION_COMMIT	The current commit hash of the destination branch.	Only on pipelines targeting a pull request.
BITBUCKET_MERGE_QUEUE_PR_IDS	The ordered list of IDs of the pull requests currently in the queue.	Only on merge-queue pipelines.
BITBUCKET_GIT_HTTP_ORIGIN	オリジンの URL。例: http://bitbucket.org/<workspace>/<repo>	All pipelines
BITBUCKET_GIT_SSH_ORIGIN	SSH オリジン。例: git@bitbucket.org:/<workspace>/<repo>.git	All pipelines
BITBUCKET_EXIT_CODE	ステップの終了コードは `after-script` セクションで使用できます。値は `0` (成功) または `1` (失敗) になります。	Only to commands within the `after-script` section of a step
BITBUCKET_STEP_UUID	ステップの UUID。	All pipelines
BITBUCKET_PIPELINE_UUID	パイプラインの UUID。	All pipelines
BITBUCKET_DEPLOYMENT_ENVIRONMENT	環境名の URL フレンドリーなバージョン。	Only on deployment steps
BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID	REST API 経由で環境にアクセスするための環境の UUID。	Only on deployment steps
BITBUCKET_PROJECT_KEY	現在のパイプラインが属するプロジェクトのキー。	All pipelines
BITBUCKET_PROJECT_UUID	現在のパイプラインが属するプロジェクトの UUID。	All pipelines
BITBUCKET_STEP_TRIGGERER_UUID	(プッシュ、マージなどを実行することによって) ビルドを開始したユーザー、およびスケジュールされたビルドの場合は、パイプラインユーザーの UUID。	All pipelines
BITBUCKET_STEP_OIDC_TOKEN	このステップを識別する Bitbucket OIDC プロバイダーによって生成された「ID トークン」。このトークンは、AWS や GCP などのリソースサーバーへの認証情報を使用しないアクセスに使用できます。詳細をご確認ください。	Only on steps configured for OIDC
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 ランナー上で実行されているパイプラインでのみ利用できます。	Only for pipelines running on Bitbucket Cloud and the Linux Docker Pipelines runner
BITBUCKET_STEP_RUN_NUMBER	現在のステップの実行番号を指定します。これは、最初の実行の 1 から始まり、特定のステップが実行された回数を識別するのに役立ちます。	All pipelines
BITBUCKET_PACKAGES_USERNAME	Specifies the 'username' to authenticate as Bitbucket Pipelines against Bitbucket Packages. This variable is to be used with BITBUCKET_PACKAGES_TOKEN.	All pipelines
BITBUCKET_PACKAGES_TOKEN	Specifies the 'the token' to authenticate as Bitbucket Pipelines against Bitbucket Packages. This variable is to be used with BITBUCKET_PACKAGES_USERNAME.	All pipelines
DOCKER_HOST	The host of the step's Docker daemon.	All pipelines
BITBUCKET_TRIGGER_PIPELINE_UUID	The UUID of the upstream pipeline that triggered the pipeline.	Pipelines triggered by: `pipeline-completed` `deployment-completed` `package-artifact-created`
BITBUCKET_TRIGGER_PIPELINE_RUN_UUID	The UUID of the pipeline run that triggered the pipeline.	Pipelines triggered by `pipeline-completed`
BITBUCKET_TRIGGER_STEP_UUID	The UUID of the step that triggered the pipeline.	Pipelines triggered by `package-artifact-created`
BITBUCKET_TRIGGER_PIPELINE_SELECTOR_TYPE	The selector type of the pipeline that triggered the pipeline.	Pipelines triggered by `pipeline-completed`
BITBUCKET_TRIGGER_PIPELINE_SELECTOR_PATTERN	The selector pattern of the pipeline that triggered the pipeline.	Pipelines triggered by `pipeline-completed`
BITBUCKET_TRIGGER_PIPELINE_STATUS	The status of the pipeline that triggered the pipeline.	Pipelines triggered by `pipeline-completed`
BITBUCKET_TRIGGER_DEPLOYMENT_UUID	The UUID of the deployment that triggered the pipeline.	Pipelines triggered by `deployment-completed`
BITBUCKET_TRIGGER_DEPLOYMENT_STATUS	The status of the deployment that triggered the pipeline.	Pipelines triggered by `deployment-completed`
BITBUCKET_TRIGGER_DEPLOYMENT_ENVIRONMENT_NAME	The name of the environment the deployment that triggered the pipeline belongs to.	Pipelines triggered by `deployment-completed`
BITBUCKET_TRIGGER_PACKAGES_PACKAGE_TYPE	The type of the package, for example `CONTAINER` or `MAVEN`.	Pipelines triggered by `package-artifact-created`
BITBUCKET_TRIGGER_PACKAGES_PACKAGE_NAME	The name of the package, for example `ubuntu` or `com.atlassian:my-library`.	Pipelines triggered by `package-artifact-created`
BITBUCKET_TRIGGER_PACKAGES_ARTIFACT_NAME	The name of the artifact, for example for Docker containers this is the ID of the manifest, such as `manifest:sha256:1646cefe9f37d36912d5a179eabef4a91ace6489377b252fe7dd3eeb062eabab`, or for Maven packages it is the version, such as `1.0.0`.	Pipelines triggered by `package-artifact-created`
BITBUCKET_TRIGGER_FIX_FLAKY_TEST_TARGET_BRANCH	The branch that the pull request containing the generated code fix for the flakey test should target. Typically your default branch where the fix needs to land.	Pipelines triggered by `fix-flaky-test`
BITBUCKET_TRIGGER_FIX_FLAKY_TEST_SOURCE_BRANCH	The pre-generated branch name the agent must use to push fixes. This is to be used as the source branch when raising the pull request to ensure linking between the flaky test and the generated pull request.	Pipelines triggered by `fix-flaky-test`
BITBUCKET_TRIGGER_TEST_CASE_FQDN	The fully qualified domain name of the flaky test. Use this to locate the exact test file and method in your codebase that the agent should fix.	Pipelines triggered by `fix-flaky-test`
BITBUCKET_TRIGGER_TEST_CASE_UUID	The UUID of the flaky test case that triggered this pipeline. Use this to look up test history, execution details, or call the API.	Pipelines triggered by `fix-flaky-test`

ユーザー定義変数

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

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

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

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

ワークスペース変数

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

プロファイルアバターからワークスペースを選択します。
上部のナビゲーションバーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウンメニューから [ワークスペース設定] を選択します。
In the menu on the left, go to Pipelines, then Workspace variables.

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

リポジトリ変数

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

From the repository, you can manage repository variables. Next to the name of your repository in the left sidebar, select More actions (…), and then select Settings. Under Pipelines, select Repository variables.

Note: Repository variables override team variables.

共有パイプライン変数

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

考慮事項

変数の値は、後のステップのビルド設定セクションにプレーンテキストで記録されます。この機能は、セキュアな変数での使用を目的としたものではありません。
変数名は、ステップ 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

入力変数

親パイプラインの変数を子パイプラインに共有できます。

考慮事項

変数の値は、パイプライン変数として子パイプラインのビルド設定セクションにプレーンテキストで記録されます。この機能は保護された変数には対応していません。保護された変数を子パイプラインに渡そうとすると、ビルドが失敗します。
pipeline ステップの入力変数は 20 個までに制限されています。
input-variables はパイプラインのライフサイクル中存続します。パイプラインを再実行すれば利用できるようになります。

例: 親パイプラインから子パイプラインに入力変数を渡します。

- step:
   name: 'Child pipeline'
   custom: a-child-pipeline
   type: pipeline
   input-variables:
      var_1: $parent_pipeline_variable
      var_2: $repository_variable_name
      var_3: $workspace_variable_name
      var_4: "static-value-1"
      var_5: "static-value-2"

デプロイ変数

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

From the repository, you can manage deployment variables in your repository’s Settings, then select Pipelines, and then select Deployments. Note: Deployment variables override both team and repository variables, and are unique to each environment.

# 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

保護された変数

You can secure a variable, which means it can be used in your scripts but its value will be hidden in the build logs (see example below). If you want to edit a secure variable, you can only give it a new value or delete it. Secure variables are stored as encrypted values. Select the padlock to secure the 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 エンコーディングなど) の照合を行います。

How to use variables in your Pipelines YAML file

Supported variables and limitations

You can use variables in your Pipelines YAML file to make your configuration more flexible and reusable. However, not all variable types are supported for templating in YAML:

Secured variables: Not supported. These values are never displayed in logs for security reasons.
Certain default variables: Not supported. These are also defined after the YAML file is parsed.

If you use Dynamic Pipelines in your workflows, variables are injected into the YAML file before any Dynamic Pipelines run. This means you can use both features together.

To template a variable in your YAML file, wrap the variable key in ${{ }}. The value is injected at runtime.

Variables must be set up in your workspace or repository settings before you use them. For details, see reference variables or workspace and repository variables

Currently, you can template these variable types in your YAML file:
- ワークスペース変数
- リポジトリ変数
- Custom pipeline variables
- Certain default variables (see the list below)

Secure variables aren’t supported for templating.

Supported default variables
- 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

Example: Using variables in your YAML file

次の例では、パイプラインの 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
Example custom pipeline variable: SERVICE_NAME = example-service

After variables are injected

image: ${{IMAGE_NAME}}
definitions:
  caches:
    test-cache: ${{CACHE_PATH}}
pipelines:
  default:
- variables:
      - name: SERVICE_NAME
    - step:
        name: 'Pipeline Step in ${{BITBUCKET_REPO_SLUG}}'in ${{SERVICE_NAME}}'
        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 in example-service'
        caches:
          - test-cache
        script:
          - echo "Hello! test cache" >> $CACHE_PATH/test.txt

Limits on Custom pipeline variable

You can only pass up to 350 custom pipeline variables in a single pipeline with a maximum combined size of 512 KB for all their values.

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

This functionality is available for pipelines using self-hosted and cloud runners.

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

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

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

サードパーティのシークレットプロバイダーが Bitbucket と通信できるようミドルウェアをコーディングします。
セルフホストランナーをご利用の場合は、サードパーティのシークレットプロバイダーに接続するように Bitbucket ランナーをセットアップします。
シークレットを取得するように Bitbucket パイプラインをセットアップします。

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

We’ve provided a sample repository to get you started. This repository contains an example java app for a third-party secret provider integration.

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

プロバイダーが Bitbucket からのシークレットリクエストに応答できるようにします。
Validate the request is coming from Bitbucket using an OIDC JWT token.
シークレットの基本的なセットを返します。

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

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

Use the Open API spec we’ve provided in the sample repository to ensure your middleware can communicate with 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 パイプラインのセットアップ

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

Enable OIDC for each pipeline step that will retrieve a secret from your provider.
プロバイダーに保存されているシークレットの名前と一致する変数を使用してください。

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

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

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

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

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

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

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

コミュニティに質問