bitbucket-pipelines.yml でランナーを設定する

Pipelines でランナーを使用するには、bitbucket-pipelines.yml ファイルのステップに実行パラメーターを追加します。ランナーは、すべての必要なラベルが付けられている、次に使用可能なランナー上で実行されます。

一致するすべてのランナーがビジー状態の場合、1 つのランナーが再び使用可能になるまでステップは待機します。なお、タイムアウトになるまでの 1 ステップあたりの最大ビルド時間は 120 分です。
リポジトリ内にすべてのラベルに一致するオンラインランナーがない場合、ステップは失敗します。

ビルド設定で Linux Shell ランナーを使用する

Linux Shell ランナーを Pipelines で使用するには、少なくとも linux.shell ラベルを持つ runs-on パラメーターをステップに追加します。ステップは、必要なラベルがすべて付いている次に利用可能な Linux Shell ランナーで実行されます。

注意

linux.shell ラベルを指定しない場合、スケジューラーはそれが Linux Docker ステップであると想定して、Linux Docker ランナーとして実行しようとします。
一致するすべての Linux Shell ランナーがビジー状態の場合は、1 つのランナーが再び利用可能になるまでステップを待機します。
リポジトリ内にすべてのラベルに一致するオンラインランナーがない場合、ステップは失敗します。

bitbucket-pipelines.yml

pipelines:
  custom:
    customPipelineWithRunnerStep:
      - step:
          name: Step 1
          runs-on: 
            - 'self.hosted'
            - 'linux.shell'
            - 'customlabel'
          script:
            - echo 'This step will run on a self-hosted Linux Shell runner.';
      - step:
          name: Step 2
          script:
            - echo "This step will run on Atlassian's infrastructure as usual.";

ビルド設定で Linux Docker ARM ランナーを使用する

Linux Shell ランナーを Pipelines で使用するには、少なくとも linux.arm64 ラベルを持つ runs-on パラメーターをステップに追加します。ステップは、必要なラベルがすべて付いている次に利用可能な Linux Docker ARM ランナーで実行されます。

ステップに atlassian/default-image を使用する場合は、ARM サポート用に atlassian/default-image:4 以上を使用する必要があります。

注意

linux.arm64 ラベルを指定しない場合、スケジューラーはそれが Linux Docker ステップであると想定して、Linux Docker ランナーとして実行しようとします。
一致するすべての Linux ARM ランナーがビジー状態の場合は、1 つのランナーが再び利用可能になるまでステップを待機します。
リポジトリ内にすべてのラベルに一致するオンラインランナーがない場合、ステップは失敗します。

bitbucket-pipelines.yml

image: atlassian/default-image:4

pipelines:
  custom:
    customPipelineWithRunnerStep:
      - step:
          name: Step 1
          runs-on: 
            - 'self.hosted'
            - 'linux.arm64'
            - 'customlabel'
          script:
            - echo 'This step will run on a self-hosted Linux ARM runner.';
      - step:
          name: Step 2
          script:
            - echo "This step will run on Atlassian's infrastructure as usual.";

ビルド設定で Windows Runner を使用する

Pipelines で Windows ランナーを使用するには、少なくとも windows ラベルを持つ runs-on パラメーターをステップに追加します。ステップは、必要なラベルがすべて付いている次に利用可能な Windows ランナーで実行されます。

注意

windows ラベルを指定しない場合、スケジューラーはそれが Linux Docker ステップであると想定して、Linux Docker ランナーとして実行しようとします。
一致するすべての Windows Runner がビジー状態の場合は、1 つのランナーが再び利用可能になるまでステップを待機します。
リポジトリ内にすべてのラベルに一致するオンラインランナーがない場合、ステップは失敗します。

bitbucket-pipelines.yml

pipelines:
  custom:
    customPipelineWithRunnerStep:
      - step:
          name: Step 1
          runs-on: 
            - 'self.hosted'
            - 'windows'
            - 'customlabel'
          script:
            - >
              Write-Host 'This step will run on a self hosted Windows runner.';
      - step:
          name: Step 2
          script:
            - echo "This step will run on Atlassian's infrastructure as usual.";

推奨事項: yaml ファイルにエスケープ文字、区切り文字、引用符などの特殊文字を含む PowerShell スクリプトが含まれていると、問題が発生する可能性があります。PowerShell スクリプトコマンドには常に折りたたみスタイルを使用することをお勧めします。

MacOS ランナーをビルド設定で使用する

MacOS ランナーを Pipelines で使用するには、少なくとも macos ラベルを持つ runs-on パラメーターをステップに追加します。ステップは、必要なラベルがすべて付いている次に利用可能な MacOS ランナーで実行されます。

注意

macos ラベルを指定しない場合、スケジューラーはそれが Linux Docker ステップであると想定して、Linux Docker ランナーとして実行しようとします。
一致するすべての MacOS ランナーがビジー状態の場合は、1 つのランナーが再び利用可能になるまでステップをキューに入れます。
リポジトリ内にすべてのラベルに一致するオンラインランナーがない場合、ステップは失敗します。

bitbucket-pipelines.yml

pipelines:
  custom:
    customPipelineWithRunnerStep:
      - step:
          name: Step 1
          runs-on: 
            - 'self.hosted'
            - 'macos'
            - 'customlabel'
          script:
            - echo 'This step will run on a self hosted MacOS runner.';
      - step:
          name: Step 2
          script:
            - echo "This step will run on Atlassian's infrastructure as usual.";

大きなステップサイズ

runs-on パラメーターには self.hosted ラベルを含める必要があります。

自社ホストランナーで実行されるステップに、追加のメモリを割り当てられます。
現時点では、有効なサイズは、1x、2x、4x、8x です。対応可能なメモリで利用できるのは、4GB、8GB、16GB、32GBです。

例: 自社ホストランナーで実行されるステップのメモリを増やす

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
          - 'my.custom.label'
        size: 8x
        script:
          - echo "This step will run on a self hosted runner with 32 GB of memory."

カスタム docker-in-docker イメージ

この機能をサポートする最小ランナーバージョンは 1.179 です。

runs-on パラメーターには self.hosted ラベルを含める必要があります。

ランナーによって、docker-in-docker デーモンをより詳細に制御できます。これで Docker サービスのカスタムイメージを指定できますが、ステップが自社ホストランナーで実行されている場合にのみ使用できます。また、Docker サービスにカスタム名を使用できます。以下の例をご参照ください。

例: 自社ホストランナーで実行されるステップにカスタム Docker イメージを使用する

既定名の Docker サービス:

definitions:
  services:
    docker: # can only be used with a self-hosted runner
      image: docker:dind

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
          - 'my.custom.label'
        services:
          - docker
        script:
          - docker info

カスタム名の Docker サービス:

definitions:
  services:
    docker-custom:
      type: docker 
      image: docker:dind

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
          - 'my.custom.label'
        services:
          - docker-custom
        script:
          - docker info

複数の Docker サービスを定義する

Docker 値を持つタイプ パラメーターをサービス定義に追加して、複数の Docker サービスを使用します。これによって、自社ホストランナーでカスタム Docker イメージを使用して、クラウドで実行されるステップに既定の Docker サービスを使用できます。

例: 複数の Docker サービスを使用する

definitions:
  services:
    docker: # default docker service
      memory: 512
    docker-custom:
      type: docker 
      image: docker:dind
      
pipelines:
  default:
    - step:
        name: Step 1
        runs-on: 
          - 'self.hosted'
          - 'my.custom.label'
        services:
          - docker-custom
        script:
          - docker info
    - step:
          name: Step 2
          services:
            - docker
          script:
            - docker info
            - echo "This step will use the defult docker service defenition.";

git クローンで SSL をスキップする

runs-on パラメーターには self.hosted ラベルを含める必要があります。

git クローン中に SSL 検証を無効にして自己署名証明書の使用を許可する、skip-ssl-verify パラメーターを追加します。

例

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
        clone:
          skip-ssl-verify: true
        script:
          - echo "Use git with a self-signed certificate"

ランナー v5 の機能

ランナーバージョン 5 以降には、次の機能があります。

Docker ベースのセルフホストランナー向け

リソースパリティ

セルフホストランナーは、Bitbucket Cloud ランナーでリソースパリティを使用できるようになりました。インフラストラクチャ上で実行されるビルドには、クラウドで実行されるビルドと同じ CPU とメモリの割り当てが適用されるため、一貫したビルドパフォーマンスが確保され、環境間でのトラブルシューティングが容易になります。

これらを使用するには、ランナーのバージョンが 5 以降であることを確認してください。ランナーを作成すると、ダウンロード URL にバージョンが含まれます。このバージョンは、ランナーを起動したときにランナーログとステップログに出力されます。

カスタムリソース制限

Docker ベースのランナーの場合、ビルドコンテナーにカスタムの CPU とメモリの制限を指定することで、既定のリソース設定を上書きできます。これは、ビルドに必要なリソースが既定よりも多い場合や少ない場合に役立ちます。

例:

pipelines:
  default:
    - step:
        runtime:
          self-hosted:
            memory: 6
            cpu: 2
        runs-on:
          - linux
        script:
          - echo 1

この例では、ランナーは 2 つの CPU と 4 GiB のメモリを使用します。

この機能を使用する場合、size 属性は無視されます。

ボリュームをマウントする

Docker ベースのランナーの場合、ホストディレクトリを Docker ボリュームとしてビルドコンテナーにマウントできます。これにより、ステップ間でデータを保持したり、ホスト上の他のプロセスとファイルを共有したりできます。

例:

pipelines:
  default:
    - step:
        runtime:
          self-hosted:
            volumes:
              - "/path/on/host:/path/in/container"
        runs-on:
          - linux
        script:
            - echo 1

この構成は、ランナーホストから /path/on/host をビルドコンテナーナー内の /path/in/container にマウントします。

すべてのセルフホストランナー向け

カスタムストレージプロバイダー (GCP/AWS) を使用する

ビルドアーティファクトとキャッシュを保存するために、Google Cloud Storage や AWS S3 などのカスタムストレージバックエンドを使用するようにランナーを設定できます。

GCP

例: OIDC を使用する場合 (推奨)

pipelines:
  default:
    - step:
        oidc: true # default is true
        runtime:
          self-hosted:
            storage:
              gcp:
                bucket: your-bucket-name
                key-file: $MY_GCP_KEY_FILE # this is the base64 encoded
        runs-on:
          - linux
        script:
            - echo 1

この場合、変数 MY_GCP_KEY_FILE の値は、ワークロード ID フェデレーションで構成されたサービスアカウントの GCP キーファイルの base64 でエンコードされたコンテンツです。

例: OIDC を使用しない場合

pipelines:
  default:
    - step:
        oidc: false # default is true
        runtime:
          self-hosted:
            storage:
              gcp:
                bucket: your-bucket-name
                key-file: $MY_GCP_KEY_FILE # this is the base64 encoded
        runs-on:
          - linux
        script:
            - echo 1

この場合、変数 MY_GCP_KEY_FILE の値は、サービスアカウントの GCP キーファイルの base64 でエンコードされたコンテンツです。

AWS

例: OIDC を使用する場合 (推奨)

pipelines:
  default:
    - step:
        oidc: true # default is true
        runtime:
          self-hosted:
            storage:
              aws:
                bucket: your-bucket-name
                region: your-aws-region # example, us-west-1
                oidc-role: my-role-arn
        runs-on:
          - linux
        script:
            - echo 1

例: OIDC を使用しない場合

pipelines:
  default:
    - step:
        oidc: false # default is true
        runtime:
          self-hosted:
            storage:
              aws:
                bucket: your-bucket-name
                region: your-aws-region # example, us-west-1
                access-key: your-access-key
                secret-key: $SECRET_KEY
        runs-on:
          - linux
        script:
            - echo 1

オプション

複数のステップ間での繰り返しを避けるために、これらの機能は options を使用して設定できます。

例:

options:
  oidc: true
  runs-on:
    - linux
  runtime:
    self-hosted:
      memory: 8092
      cpu: 2
      storage:
        gcp:
          bucket: your-bucket-name
          key-file: $MY_GCP_KEY_FILE # this is the base64 encoded
pipelines:
  default:
    - step:
        script:
            - echo 1
    - step:
        script:
            - echo 2

この例では、両方のステップが options で設定されたプロパティを受け取ります。

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

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

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

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

コミュニティに質問

bitbucket-pipelines.yml でランナーを設定する

ビルド設定で Linux Shell ランナーを使用する

ビルド設定で Linux Docker ARM ランナーを使用する

ビルド設定で Windows Runner を使用する

MacOS ランナーをビルド設定で使用する

大きなステップ サイズ

カスタム docker-in-docker イメージ

複数の Docker サービスを定義する

git クローンで SSL をスキップする

ランナー v5 の機能

Docker ベースのセルフホスト ランナー向け

リソース パリティ

カスタム リソース制限

ボリュームをマウントする

すべてのセルフホスト ランナー向け

カスタム ストレージ プロバイダー (GCP/AWS) を使用する

GCP

AWS

オプション

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

大きなステップサイズ

Docker ベースのセルフホストランナー向け

リソースパリティ

カスタムリソース制限

すべてのセルフホストランナー向け

カスタムストレージプロバイダー (GCP/AWS) を使用する