Lesstep
Bitbucket Cloud・Pipelines・2026年11月2日に確認

Bitbucket Pipelines：「Container 'build' failed to pull image」

スクリプトが動く前に、Pipelines はステップかファイル全体の image: に書いたイメージを引き、そこからビルドのコンテナを起こします。引けないと、ステップは最初のコマンドの前で止まり、次のような行が出ます。Atlassian の課題 BCLOUD-23970（英語）に載っている例です。

Container 'build' failed to pull image: 'failed to pull and unpack image "crg.apkg.io/...": failed to resolve reference "crg.apkg.io/...": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed'

行の後ろの部分は、レジストリの返事です。レジストリは、名前の誤りにも認証の不足にも同じ「repository does not exist or may require authorization」を返すので、両方を確かめます。

名前とタグ

image の下の username と password

image:
  name: account-name/openjdk:8
  username: $DOCKER_HUB_USERNAME
  password: $DOCKER_HUB_PASSWORD

ほかのレジストリも、アドレスをまるごと書いて同じ2つの欄を使います。email の欄はもう使われておらず、要らないとページにあります。

値が合っているはずなのに断られるときについて、Atlassian の記事 Failed to pull private image in Bitbucket pipelines（英語・2025年9月26日更新）は、いちばんありそうな原因に変数の前後の空白を挙げています。セキュアな変数は中身を読み返せないので、消して作り直します。

AWS ECR

Atlassian のページには2つの方法があります。1つはアクセスキーです。

image:
  name: <account-id>.dkr.ecr.<region>.amazonaws.com/openjdk:8
  aws:
    access-key: $AWS_ACCESS_KEY
    secret-key: $AWS_SECRET_KEY

もう1つは、ページが勧めている OpenID Connect で、aws: oidc-role: にロールの ARN を書きます。OpenID Connect を使用して Pipelines で AWS ECR イメージを使用するでは、ステップにも oidc: true を書き、ロールには ecr:GetAuthorizationToken と、リポジトリを読む操作（ecr:BatchGetImage・ecr:GetDownloadUrlForLayer・ecr:BatchCheckLayerAvailability など）を許しています。ID プロバイダと信頼ポリシーは、Pipelines から引き受けるほかのロールと同じです（OIDC で AWS）。

- step:
    image:
      name: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest
      aws:
        oidc-role: arn:aws:iam::123456789012:role/pipelines-ecr-access
    oidc: true
    script:
      - echo "hello world"

Atlassian の例とは、違う点が1つあります。例はイメージを ...amazonaws.com/repository/my-repo:latest と書いていますが、ECR のイメージのアドレスに repository/ は入りません。AWS のイメージのプルのページは aws_account_id.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest です。repository/ が付くのは、ポリシーの ARN（arn:aws:ecr:...:repository/my-repo）のほうです。

Google Artifact Registry

Atlassian のページは、いまも Google Container Registry（gcr.io）の例で、username に _json_key、password にサービスアカウントの鍵を書いています。Container Registry は 2025年3月18日に終わり、Artifact Registry に載せた gcr.io のアドレスはそのまま使えます（Google の Container Registry からの移行）。<location>-docker.pkg.dev のアドレスには、Google の Artifact Registry に対して Docker を認証するが同じユーザー名の _json_key を使っています。鍵のファイルはダウンロードしたまま渡し、ファイル全体を base64 にしたときは _json_key_base64 にします。

image:
  name: us-central1-docker.pkg.dev/my-project/my-repo/build-env:1.0
  username: _json_key
  password: '$GAR_JSON_KEY'

レジストリのログには、成功した pull の前に断られたリクエストが1つずつ残ることがあります。Atlassian の課題 BCLOUD-23353（英語）によると、Pipelines はまず認証なしで、次に認証つきで取りに行きます。課題は 2025年に変更なしで閉じられ、pull そのものは通ります。

Bitbucket 自身のコンテナのレジストリ

Bitbucket Packages（crg.apkg.io/<workspace>/...）のイメージについて、BCLOUD-23970 の例は username に Atlassian アカウントのメールアドレス、password に API トークンを書いています。この課題が、このページの最初のエラーです。IP Allowlist を有効にしたワークスペースでは、pull が insufficient_scope で落ちます。2026年1月に立ってまだ開いたままで、挙がっている回避策は Allowlist を切ることだけです。

ARM だけのイメージ

クラウドのステップは、ARM を指定しない限り x86 で動きます。Atlassian のステップ オプションに runtime: cloud: arch: arm があり、Standard と Premium のプランで使えます。ARM 向けにだけ作ったイメージは x86 では動きません。push のしかたによって、pull が no match for platform in manifest で止まるか、pull は通って最初のコマンドが exec format error で落ちます。両方の向けにイメージを作るか、ステップを ARM で動かします。

- step:
    runtime:
      cloud:
        arch: arm
    image: my-arm-image:1.0
    script:
      - ./build.sh

いくつものビルドが同時に落ちる

別々のリポジトリで同じころに pull が落ちるなら、Bitbucket のステータスページを見ます。2024年2月には、そこに載った障害の間、セルフホストのランナーが「Unable to pull image」で止まりました。Docker Hub の pull の上限でも toomanyrequests で止まります（「You have reached your pull rate limit」）。

IntelliJ IDEA で Bitbucket Pipelines を見る

Pipeline Inbox for Bitbucket Pipelines は、Lesstep が作っている JetBrains IDE（2024.1 以降）のプラグインです。Bitbucket Cloud の全部のリポジトリのパイプラインを IDE のツールウィンドウに並べ、ステップ、失敗したステップと止まったコマンド、Bitbucket が書くそばから伸びるステップのログを見せます。一覧・ステップ・ログは無料。パイプラインの実行・やり直し・停止は Pro（月 US$1.50・30日の無料試用つき）。

JetBrains Marketplace で入れる

Atlassian・Bitbucket・Bitbucket Pipelines は Atlassian の商標、Docker は Docker, Inc. の商標、AWS は Amazon.com, Inc. またはその関連会社の商標、Google Cloud は Google LLC の商標、IntelliJ IDEA は JetBrains s.r.o. の商標です。このページは Atlassian・Docker・Amazon・Google・JetBrains のいずれとも提携しておらず、承認も受けていません。

ほかに：サービスに「Connection refused」（MySQL・PostgreSQL・Redis） · 「Not authorized to perform sts:AssumeRoleWithWebIdentity」（OIDC で AWS） · テストの結果が出ない · 変数が空になる · 「Host key verification failed」（SSH） · 「Cannot connect to the Docker daemon」 · 「authorization denied by plugin pipelines」（Docker） · 「Container 'docker' exceeded memory limit.」 · push したのに Pipelines が動かない · 「Container 'Build' exceeded memory limit.」 · 「Exceeded build time limit of 120 minutes」 · キャッシュが効かない · 「unexpected system error」 · 「command not found」 · サブモジュールを取ってこない · 「We couldn't clone the repository」 · 「No online runner available」 · 「No space left on device」 · 「Step exceeded processing limits」 · 次のステップにアーティファクトが無い · 前は通ったビルドが今は落ちる · Build setup に時間がかかる · ビルド時間を使い切った · 「Permission denied to update branch」 · 「You have reached your pull rate limit」（Docker Hub） · 「There is an error in your bitbucket-pipelines.yml」 · 「This pipeline was paused」（デプロイ） · スケジュールしたパイプラインが動かない · IntelliJ IDEA の Bitbucket Pipelines 用プラグインの比較 · English