Cache, service container, step config, and export pipelines definitions

The definitions option allows you to define custom dependency caches, step config, and service containers (including database services) for Bitbucket Pipelines.

Caches, services, and step config for pipelines

The following options can be used for defining caches, step config, and service containers:

定義

定義

definitions プロパティは、パイプライン構成の別の場所で使用されるリソースを定義するために使用されます。リソースには、以下が含まれる可能性があります。

別々の Docker コンテナーで実行されるサービス – 「データベースとサービスコンテナー」をご参照ください。
キャッシュ – 「キャッシュ」をご参照ください。
Step config - a reusable set of step options that a step can inherit - see Step config.
YAML アンカー - YAML を分割して定義して使いやすくする方法。 YAML アンカー」を参照してください。

プロパティ — definitions

必須 — いいえ

データタイプ — ブロック (YAML 仕様 - ブロックマッピング)

指定可能な親プロパティ — YAML ルート (definitions は必ず最上位のプロパティとなります)

Allowed child properties — Requires one or more of the caches, step config, and services properties.

例 — definitions を使用して、カスタムキャッシュとデータベースサービスをパイプラインステップに追加する

definitions:
  caches:
    bundler-packages: vendor/bundle   
  services:
    my-mariadb:
      image: mariadb:latest
      variables:
        MARIADB_USER: $MY_MARIADB_USER
        MARIADB_PASSWORD: $MY_MARIADB_PASSWORD
        MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD

pipelines:
  default:
    - step:
        name: Hello world example
        services:
          - my-mariadb
        caches:
          - bundler-packages
        script:
          - ruby -e 'print "Hello, World\n"'

例 — YAML アンカーを使用して、再利用可能なステップを作成する

definitions: 
  steps:
    - step: &build-test
        name: Build and test
        script:
          - mvn package
        artifacts:
          - target/**

pipelines:
  branches:
    develop:
      - step: *build-test
    main:
      - step: *build-test

キャッシュ

Bitbucket Pipelines では、ビルドの依存関係やディレクトリのキャッシングをサポートし、ビルドの高速化と消費されるビルド時間の削減を実現しています。

定義済みのキャッシュもいくつか利用可能です。定義済みのキャッシュの完全なリストについては「キャッシュ — 定義済みのキャッシュ」をご確認ください。

caches オプションの使用に関する詳細は、「キャッシュ」を参照してください。

プロパティ — caches

必須 — いいえ

データタイプ — 改行で区切られた名前と値のペアのブロック (YAML 仕様 - ブロックマッピング)。名前はキャッシュ名、値は次のいずれかです。

ファイルまたはディレクトリのパスを表す文字列 (glob パターンを使用できます)
キャッシュキーとパスオプションを含むノード

指定可能な親プロパティ — definitions

指定可能な子プロパティ — 次のいずれかです。

ファイルまたはディレクトリパスを表す文字列を提供する場合: なし
キーとパスのオプションを使用している場合: キャッシュ名 (caches の下にネストされます)

例 — caches オプションで Ruby プロジェクト用のカスタム依存関係キャッシュを作成する

definitions:
  caches:
    my-bundler-cache: vendor/bundle

pipelines:
  default:
    - step:
        caches:
          - my-bundler-cache # Cache is defined above in the definitions section
        script:
          - bundle install --path vendor/bundle
          - ruby -e 'print "Hello, World\n"'

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、caches オプションを使用してカスタム依存関係キャッシュを作成する

keyfiles オプションは、変更を監視するファイルを指定するために使用します。path で指定されたキャッシュは、key files の変更に基づいてバージョン管理されます。

definitions:
  caches:
    my-bundler-cache:
      key:
        files:
          - Gemfile.lock
          - "**/*.gemspec" # glob patterns are supported for cache key files
      path: vendor/bundle

pipelines:
  default:
    - step:
        caches:
          - my-bundler-cache # Cache is defined above in the definitions section
        script:
          - bundle install --path vendor/bundle
          - ruby -e 'print "Hello, World\n"'

鍵 (キー)

キャッシュの key オプションは、キャッシュの新しいバージョンをいつ作成するかを決定する基準を定義します。バージョン管理に使用されるキャッシュキーは、files が定義されたハッシュに基づいています。

プロパティ — key

必須 — いいえ

データタイプ — files のブロック

指定可能な親プロパティ — キャッシュ名 (cachesの下にネストされます)

指定可能な子プロパティ — files

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの key オプションを使用してカスタム依存関係キャッシュを作成する

definitions:
  caches:
    my-bundler-cache:
      key:
        files:
          - Gemfile.lock
          - "**/*.gemspec" # glob patterns are supported for cache key files
      path: vendor/bundle

pipelines:
  default:
    - step:
        caches:
          - my-bundler-cache # Cache is defined above in the definitions section
        script:
          - bundle install --path vendor/bundle
          - ruby -e 'print "Hello, World\n"'

キーファイル

キャッシュキーの files プロパティには、変更を監視するリポジトリ内のファイルがリストされます。1 つ以上の files のハッシュが変更されると、新しいバージョンのキャッシュが作成されます。

プロパティ — files

必須 — はい

データタイプ — ファイル名に一致する文字列のリスト (glob パターンを使用できます)

指定可能な親プロパティ — key

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュキーの files オプションを使用してカスタム依存関係キャッシュを作成する

definitions:
  caches:
    my-bundler-cache:
      key:
        files:
          - Gemfile.lock
          - "**/*.gemspec" # glob patterns are supported for cache key files
      path: vendor/bundle

pipelines:
  default:
    - step:
        caches:
          - my-bundler-cache # Cache is defined above in the definitions section
        script:
          - bundle install --path vendor/bundle
          - ruby -e 'print "Hello, World\n"'

パス

キャッシュの path オプションは、キャッシュするパスを定義します。これは、ソースリポジトリ外の場合があります。

プロパティ — path

必須 — いいえ

データタイプ — 文字列としてのユーザー定義のファイルパス (glob パターンを使用できます)

指定可能な親プロパティ — キャッシュ名 (cachesの下にネストされます)

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの path オプションを使用してカスタム依存関係キャッシュを作成する

definitions:
  caches:
    my-bundler-cache:
      key:
        files:
          - Gemfile.lock
          - "**/*.gemspec" # glob patterns are supported for cache key files
      path: vendor/bundle

pipelines:
  default:
    - step:
        caches:
          - my-bundler-cache # Cache is defined above in the definitions section
        script:
          - bundle install --path vendor/bundle
          - ruby -e 'print "Hello, World\n"'

サービス

Bitbucket Pipelines can create separate Docker containers for services, which results in faster builds, and easy service editing. For details on creating services see Databases and service containers. This services option is used to define the service, allowing it to be used in a pipeline step.

シークレットとログイン認証情報漏洩を防ぐために、ユーザー定義のパイプライン変数として保存する必要があります。詳細は「変数とシークレット — ユーザー定義の変数」をご参照ください。

プロパティ — services

必須 — いいえ

データタイプ — ブロック (YAML 仕様 - ブロックマッピング)

指定可能な親プロパティ — definitions

指定可能な子プロパティ — ユーザー定義の文字列。この文字列はサービスの名前になります。

例 — サービス定義を使用して、データベースサービスをビルドステップに追加する

definitions:
  services:
    my-service-name:
      image: mariadb:latest
      variables:
        MARIADB_USER: $MY_MARIADB_USER
        MARIADB_PASSWORD: $MY_MARIADB_PASSWORD
        MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD

pipelines:
  default:
    - step:
        name: Hello world example
        services:
          - my-service-name
        script:
          - echo "Hello, World"

画像

サービスでのimageオプションの使用など、imageオプションの詳細については、「Docker イメージオプション」を参照してください。

メモリ

memory オプションは、サービスコンテナーで利用可能なメモリ (メガバイト単位) を制限するために使用されます。4096MB (size: 2x ビルドの場合は 8192 MB) は、スクリプトやパイプラインサービスを含めて、stepに割り当てることができるメモリの総量です。たとえば、サービスが 3072 MB を必要とする場合、そのサービスによるステップの実行に使用できるのは 1024MB のみとなります。サービスコンテナーのメモリ制限に関する詳細は、「データベースとサービスコンテナー — サービスメモリの制限」をご参照ください。

プロパティ — memory

必須 — いいえ

データタイプ — 整数

指定可能な値 — 128 ～ 4096 (size: 2x ビルドの場合は 256 ～ 8192) MB。

既定値 — 1024

指定可能な親プロパティ — サービス名 (services の下にネストされます)

例 — memory オプションを使用して、サービスコンテナーのメモリを 512MB に制限する

definitions:
  services:
    my-postgresql-db:
      image: postgres:latest
      memory: 512
      variables:
        POSTGRES_PASSWORD: $MY_POSTGRES_PASSWORD

pipelines:
  default:
    - step:
        name: Hello world example
        services:
          - my-postgresql-db
        script:
          - echo "Hello, World"

タイプ

自社ホストのパイプラインランナーでのみ利用できます。

type オプションは、Docker サービスコンテナー (Docker-in-Docker を実行する) を指定するために使用されます。対象となるのは次のとおりです。

カスタム名の Docker-in-Docker サービスコンテナー
複数の Docker-in-Docker サービスコンテナー

詳細情報

カスタムの Docker-in-Docker サービスを追加するには、「 bitbucket-pipelines.yml でランナーを設定する — カスタム Docker-in-Docker イメージ」をご参照ください。
Docker-in-Docker サービスを使用するには、「Bitbucket Pipelines で Docker コマンドを実行する」を参照してください。

プロパティ — type

必須 — いいえ

データタイプ — 文字列

指定可能な値 — docker

指定可能な親プロパティ — サービス名 (services の下にネストされます)

例 — type オプションを使用して、複数の Docker-in-Docker サービスを追加する

definitions:
  services:
    docker: # Default Docker-in-Docker service
      image: docker:dind
    my-docker-in-docker-name:
      image: docker:latest
      type: docker
    docker-custom:
      type: docker 
      image: docker:dind

pipelines:
  default:
    - step:
        script:
          - docker version
          - docker run hello-world
        services:
          - docker
    - step:
        script:
          - docker version
          - docker run hello-world
        services:
          - my-docker-in-docker-name
    - step:
        script:
          - docker version
          - docker run hello-world
        services:
          - docker-custom

Variables

サービスの variables オプションは、環境変数をサービスコンテナーに渡すために使用され、通常はサービスの設定に使用されます。サービスの作成に関する詳細は、「データベースとサービスコンテナー」をご参照ください。

プロパティ — variables

必須 — いいえ

データタイプ — 改行で区切られた名前と値のペアのブロック (YAML 仕様 - ブロックマッピング)

指定可能な親プロパティ — サービス名 (services の下にネストされます)

例 — variables を使用して、MariaDB サービスコンテナーをセットアップする

definitions:
  services:
    my-service-name:
      image: mariadb:latest  # Official MariaDB image from DockerHub: https://hub.docker.com/_/mariadb/
      variables:
        MARIADB_USER: $MY_MARIADB_USER
        MARIADB_PASSWORD: $MY_MARIADB_PASSWORD
        MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD

pipelines:
  default:
    - step:
        name: Hello world example
        services:
          - my-service-name
        script:
          - echo "Hello, World"

例 — variables を使用して、PostgreSQL サービスコンテナーをセットアップする

definitions:
  services:
    my-postgresql-db:
      image: postgres:latest  # Official PostgreSQL image from DockerHub: https://hub.docker.com/_/postgres
      variables:
        POSTGRES_PASSWORD: $MY_POSTGRES_PASSWORD

pipelines:
  default:
    - step:
        name: Hello world example
        services:
          - my-postgresql-db
        script:
          - echo "Hello, World"

Step config

A step config is a named, reusable set of step options. Define it once under definitions, then reference it from any step with the config option. Every option in a step config is optional, and any option you set on the step itself overrides the one it inherits.

Use a step config to avoid repeating the same image, size, caches, or services across steps that share a build environment.

Property — step-config
Required — No
Data type — Block (YAML spec - Block Mapping)
Allowed parent properties — definitions
Allowed child properties — A user-defined string. This string will be the name of the step config. Each named step config accepts the same options as a step, except config.

How a step config is merged into a step

An option set on the step always wins over the same option in the step config.
Merging happens at the top level only. There is no deep merge. A list or block in the step replaces the one in the step config instead of being added to it.
Your configuration is validated after the merge.
A step config cannot reference another step config. The config option is not allowed inside a step config definition.

The default step config

default is a special step config name. A step that sets config: default is valid even when no default step config is defined, in which case the step inherits nothing. Every other name must exist under definitions.step-config, or your configuration fails to parse.

A step won’t automatically pick the default step config, unless it has been explicitly configured.

The custom pipelines that Bitbucket injects for the Default system agents set config: default. Defining a default step config is how you control the options for the built-in system agents. See Default system agents for Agentic Pipelines.

definitions:
  caches:
    bundler-packages: vendor/bundle
  services:
    my-mariadb:
      image: mariadb:latest
  step-config:
    integration:
      image: ruby:3.3
      size: 4x
      caches:
        - bundler-packages
      services:
        - my-mariadb
pipelines:
  default:
    - step:
        config: integration
        name: Integration tests
        script:
          - bundle install
          - bundle exec rake test:integration
    - step:
        config: integration
        name: Contract tests
        size: 2x
        script:
          - bundle exec rake test:contract

Both steps inherit the image, caches, and services from the integration step config. The second step sets its own size, which overrides the 4x in the step config.

Example — using the default step config for agentic steps

# Enable failed step fixer system agent under workspace settings -> agentic pipelines
# Then use `default` step-config to modify the settings for it.
definitions:
  step-config:
    default:
      image: my-org/agent-base:latest
      size: 2x

パイプライン - Bitbucket Premium のみ

pipelines 変数で定義されているすべてのパイプラインがエクスポートされ、同じワークスペース内の他のリポジトリによってインポートできます。

プロパティ — pipelines

必須 — いいえ

データタイプ — 改行で区切られた名前と値のペアのブロック (YAML 仕様 - ブロックマッピング)。名前はパイプライン名、値はパイプラインです。

指定可能な親プロパティ — definitions

指定可能な子プロパティ — step、stage、または parallel プロパティが 1 つ以上必要です。

例 — `export-pipeline` という名前で、1 つのステップが定義されているパイプラインをエクスポートする

export: true

definitions:
  caches:
  services:
  pipelines:
    export-pipeline:
      - step:
        script:
          - echo hello

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

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

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

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

コミュニティに質問

Cache, service container, step config, and export pipelines definitions

Caches, services, and step config for pipelines

定義

例 — definitions を使用して、カスタム キャッシュとデータベース サービスをパイプライン ステップに追加する

例 — YAML アンカーを使用して、再利用可能なステップを作成する

キャッシュ

例 — caches オプションで Ruby プロジェクト用のカスタム依存関係キャッシュを作成する

例 — ファイル チェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、caches オプションを使用してカスタム依存関係キャッシュを作成する

鍵 (キー)

例 — ファイル チェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの key オプションを使用してカスタム依存関係キャッシュを作成する

キー ファイル

例 — ファイル チェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュ キーの files オプションを使用してカスタム依存関係キャッシュを作成する

パス

例 — ファイル チェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの path オプションを使用してカスタム依存関係キャッシュを作成する

サービス

例 — サービス定義を使用して、データベース サービスをビルド ステップに追加する

画像

メモリ

例 — memory オプションを使用して、サービス コンテナーのメモリを 512MB に制限する

タイプ

例 — type オプションを使用して、複数の Docker-in-Docker サービスを追加する

Variables

例 — variables を使用して、MariaDB サービス コンテナーをセットアップする

例 — variables を使用して、PostgreSQL サービス コンテナーをセットアップする

Step config

How a step config is merged into a step

The default step config

Example — using a step config to share a build environment between steps

Example — using the default step config for agentic steps

パイプライン - Bitbucket Premium のみ

例 — export-pipeline という名前で、1 つのステップが定義されているパイプラインをエクスポートする

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

例 — definitions を使用して、カスタムキャッシュとデータベースサービスをパイプラインステップに追加する

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、caches オプションを使用してカスタム依存関係キャッシュを作成する

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの key オプションを使用してカスタム依存関係キャッシュを作成する

キーファイル

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュキーの files オプションを使用してカスタム依存関係キャッシュを作成する

例 — ファイルチェックサムベースのハッシュ化を用いる Ruby プロジェクト向けに、キャッシュの path オプションを使用してカスタム依存関係キャッシュを作成する

例 — サービス定義を使用して、データベースサービスをビルドステップに追加する

例 — memory オプションを使用して、サービスコンテナーのメモリを 512MB に制限する

例 — variables を使用して、MariaDB サービスコンテナーをセットアップする

例 — variables を使用して、PostgreSQL サービスコンテナーをセットアップする

例 — `export-pipeline` という名前で、1 つのステップが定義されているパイプラインをエクスポートする