自動ビルドの設定

読む時間の目安: 4 分

自動ビルドはどのように動くか

Docker Hub においては、外部リポジトリ内のソースコードから自動的にイメージをビルドして、出来上がったイメージをリポジトリに自動プッシュすることができます。

自動ビルド（automated builds または autobuilds）を設定する際には、Docker イメージとしてビルドしたいブランチとタグの一覧を生成します。 その一覧に示されたイメージタグに対してのソースコードブランチ（たとえば GitHub 上）にソースをプッシュすると、このプッシュによって新たなビルドを起動するウェブフックが用いられます。 これによって Docker イメージが作り出されます。 そしてビルドされたイメージは Docker Hub レジストリにプッシュされます。

メモ

自動ビルドの設定が行われているリポジトリであってもdocker pushを使えば、それまでと変わらずにビルド済イメージをプッシュすることができます。

自動テストを設定すれば、自動ビルドが行われた直後、そしてレジストリへのプッシュが行われる前に、そのテストが実行されます。 このようなテストを利用すれば CI ワークフローにおいて、テストに失敗したビルドイメージはプッシュを行わないといったことが可能になります。 自動テスト自体は、レジストリに対してイメージをプッシュするものではありません。 イメージの自動テストに関する詳細はこちらを参照してください。

購入している プラン によっては、同時ビルドを行うこともできます。 つまりN個の自動ビルドを同時に実行します。 Nという数値は、購入しているプランにおいて設定します。 N+1個めのビルドが実行されると、これに続くビルドはキューに入り、後に実行されます。

キューに待機されるビルドの総数は 30 個に制限されていて、それ以上のビルド要求は破棄されます。 同時ビルド数は Pro プランでは 5、Team プラン、Business プランでは 15 です。

自動ビルドの設定

Docker Hub 上のリポジトリにおいては、ソースプロバイダーに対して新たなソースコードをプッシュした際に、イメージを自動的にビルドするように設定することができます。 自動テスト を設定している場合は、テストに成功したイメージのみがプッシュされます。

自動ビルドは既存のリポジトリに追加することができ、新規にリポジトリ生成を行った際に追加することもできます。

1. Repositories セクションからリポジトリの詳細画面を開きます。

2. Builds タブをクリックします。

3. 自動ビルドの設定を初めて行う場合は、イメージのソースコードを保存しているコードリポジトリサービス（GitHub または Bitbucket）を選択します。 これを行うと、コードリポジトリサービスに リンク するための設定画面にリダイレクトされます。

   別の方法として、既存の自動ビルドに対するビルド設定を行っている場合は、Configure automated builds（自動ビルドの設定）をクリックします。

4. Docker イメージを作り出す source repository（ソースリポジトリ）を選択します。

   ソースコードプロバイダーにおいては、組織やユーザー（その 名前空間）の指定が必要になるときもあります。 名前空間を選択しておけば、そのソースコードリポジトリが Select repository のドロップダウンリストに表示されるようになります。

5. 任意の作業として autotests（自動テスト）を有効にします。

6. デフォルトの Build Rules（ビルドルール）を確認し、必要に応じて プラス記号 をクリックして追加のビルドルールを設定します。

   ビルドルール とは、ソースコードリポジトリの内容に基づいて Docker Hub が何をイメージとしてビルドするのか、またビルドしたイメージを Docker リポジトリ内にてどのようにタグづけを行うかを制御します。

   デフォルトのビルドルールがすでに準備されています。 このルールは編集したり削除したりすることができます。 デフォルトのルールでは、ソースコードリポジトリ内のmasterブランチからビルドを行うものとして設定されています。 そして生成する Docker イメージにはlatestというタグをつけます。

7. 各ブランチやタグに対して Autobuild トグルを使って、自動ビルドの有効、無効を設定します。

   自動ビルドが有効として設定されたブランチやタグだけがビルド、テストされ、さらに そこから生成されたイメージだけがリポジトリにプッシュされます。 自動ビルドを無効に設定したブランチは（リポジトリレベルで有効になっている場合）テスト目的でビルドされますが、ビルドされた Docker イメージはリポジトリにプッシュされません。

8. 各ブランチやタグに対して Build Caching トグルを使って、ビルドキャッシュの有効、無効を設定します。

   ビルドキャッシュ は、大きなイメージを頻繁に生成したり、多くの依存パッケージを有するイメージを生成したりする際に、ビルド時間の短縮に役立ちます。 ビルド時に依存関係をすべて解決したい場合や、ローカルでビルドする方が早いくらいの大規模レイヤーがある場合などでは、ビルドキャッシュを無効にしておきたい場合があるかもしれません。

9. Save をクリックして設定を保存します。 または Save and build をクリックして、保存とともに初回のテストを実施します。

   ソースコードリポジトリにはウェブフックが自動的に追加されます。 これによって Docker Hub 上へのプッシュがすべて通知されるようになります。 1 つまたは複数のタグに対するソースとして一覧にあげられているブランチに対してのみ、プッシュからビルドが起動されます。

ビルドルールの設定

自動ビルドを設定すると、デフォルトで基本的なビルドルールが生成されます。 このデフォルトルールは、ソースコードリポジトリ内のmasterブランチへの変更を監視するものです。 そしてmasterブランチのソースをビルドして Docker イメージにlatestというタグづけを行います。

Build Rules（ビルドルール）のセクションにおいて、ビルドするソースを必要な分だけ入力します。

各ソースに対して以下を行います。

• Source type（ソースタイプ）として tag（タグ）または branch（ブランチ）のいずれをビルドするかを選びます。 ビルドシステムがソースコードリポジトリ内のどちらを見にいくかを指示するものです。

• ビルドを行う Source（ソース）ブランチまたはタグの名前を入力します。

  自動ビルドの設定を初めて行う場合は、デフォルトのビルドルールが設定されます。 このデフォルトルールは、ソースコード内のmasterブランチからビルドを行うものとしています。 そして生成される Docker イメージにlatestというタグをつけます。

  ビルド対象とするソースのブランチやタグの指定において、正規表現を用いることもできます。 詳しくは 正規表現 を参照してください。

• そのソースからビルドされる Docker イメージにおいて、適用するタグ名を入力します。

  ソース指定にあたって正規表現を用いた場合、マッチしたグループを用いて、タグ名の一部分に利用することができます。 詳しくは 正規表現 を参照してください。

• Dockerfile location（Dockerfile の場所）として、ソースコードリポジトリのルートからの相対パスを指定します。 Dockerfile がリポジトリのルートにあるのであれば、このパス設定は/のままとしてください。

メモ

Docker Hub がソースコードリポジトリからブランチをプルする際には、shallow クローン（指定ブランチの最新履歴のみのクローン）を行います。 詳しくは 自動ビルドや自動テストに対する高度なオプション を参照してください。

ビルドにおける環境変数

自動ビルドの設定の際には、環境変数の値をビルド時に利用するように設定できます。 ビルド時の環境変数は Build environment variables セクションの横にあるプラス記号をクリックして追加します。 そして変数名と値を入力します。

Docker Hub の UI 画面から変数値を設定すると、hooksファイル内に設定したコマンドからこれを利用することができます。 ただしこの情報は保存されるため、Docker Hub リポジトリに対するadmin権限を有するユーザーしか、その値を参照することはできません。 つまりこれを利用すれば、アクセストークンや機密にしておきたい各種情報を安全に保存しておくことができることになります。

メモ

ビルド設定画面上から設定した変数は、ビルド処理において のみ 利用されます。 したがってサービスにおいて利用している環境変数（たとえばサービスリンクの生成時に利用するもの）とは混同しないようにしてください。

アクティブなビルドの確認

リポジトリにおけるビルド概要は、リポジトリの General（一般）タブおよび Builds（ビルド）タブにおいて見ることができます。 また Builds タブでは、色づけされたバーチャートによってビルドのキュー時間や間隔を見ることもできます。 いずれの画面においてもリポジトリの各タブごとに、ビルドが中断しているもの、実行中のもの、成功したもの、失敗したものが確認できます。

いずれの画面からでもビルドジョブをクリックすれば、ビルド結果を見ることができます。 ビルド結果にはビルドジョブに関する情報として、ソースリポジトリとブランチ（あるいはタグ）、ビルド時間、生成時刻、生成場所、ビルド処理を行ったユーザー名前空間が示されます。

ビルドのキャンセルまたは再実行

ビルド要求がキューに入っている、あるいは実行されている場合に、General タブや Builds タブにおけるビルド報告リンクの横には Cancel アイコンが表示されます。 ビルド結果のページから、あるいは Timeline タブのログ表示から Cancel ボタンをクリックすることもできます。

ビルドが失敗した場合、General タブあるいは Builds タブのビルド報告の行の横に Retry（再実行）アイコンが表示されます。 またビルド報告のページや Timeline ログにおいても Retry ボタンが表示されます。

メモ

ビルド詳細を確認しているリポジトリが組織に属したものである場合、Cancel ボタンや Retry ボタンは、そのリポジトリに対してRead & Write（読み書き）の権限がある場合にのみ表示されます。

自動ビルドの無効化

自動ビルドはブランチごと、タグごとに有効化されます。 無効化したり再び有効化することは簡単です。 たとえばコードに対して大々的にリファクタリングを行うような場合に、ビルドを手動で行う必要があり、そういった場合に無効化を行いたくなります。

自動ビルドを無効化するには以下を行います。

1. Repositories ページにおいて、1 つのリポジトリをクリックして Builds タブを選びます。

2. リポジトリのビルド設定を編集するために Configure automated builds（自動ビルドの設定）をクリックします。

3. Build Rules（ビルドルール）セクションにおいて、自動ビルドを無効にしたいブランチまたはタグを選択します。

4. 設定行の横にある autobuild（自動ビルド）トグルをクリックします。

   無効を指定するとトグルボタンは灰色に変わります。

5. Save（保存）をクリックして変更を保存します。

高度な自動ビルドオプション

自動ビルドを設定するにはビルドルールにおいて、最低でもソースブランチ（またはタグ）と目的の Docker タグの指定が必要です。 これ以外に指定可能な内容として、ビルドを行う Dockerfile の場所、ビルドに利用するファイルへのパス（ビルドコンテキスト）設定、複数ブランチやタグの指定、正規表現（regex）利用によるソースコードの動的指定やタグの動的生成などがあります。

このオプションは、各リポジトリにおける Build configuration（ビルド設定）画面から利用することができます。 左側のナビゲーションから Repositories をクリックし、編集対象とするリポジトリをクリックします。 そして Builds タブを選んで、Configure Automated builds（自動ビルドの設定）をクリックします。

タグビルドやブランチビルド

自動ビルドの設定においては、特定のブランチまたはタグへのプッシュからビルドが実行されるように設定することができます。

1. Build Rules（ビルドルール）セクションにおいてプラス記号をクリックして、ビルド対象のソースを追加します。

2. ビルド対象とする Source type（ソースタイプ）を選択します。 tag（タグ）または branch（ブランチ）のいずれかです。

   これはビルドシステムがソースコードリポジトリ内のどちらを見にいくかを指示するものです。

3. ビルドを行う Source（ソース）ブランチまたはタグの名前を入力します。

   名前をそのまま入力します。 あるいは正規表現を用いて、ビルド対象とするソースブランチまたはタグを表現することもできます。 詳しくは 正規表現 を参照してください。

4. そのソースからビルドされる Docker イメージにおいて、適用するタグ名を入力します。

   ソース指定にあたって正規表現を用いた場合、マッチしたグループを用いて、タグ名の一部分に利用することができます。 詳しくは 正規表現 を参照してください。

5. 新たに設定するビルドに対して、上の手順 2 から 4 を繰り返します。

ビルドコンテキストと Dockerfile の場所指定

ソースコードリポジトリ内でのファイル構成がさまざまであるため、イメージビルドに必要なファイルがリポジトリのルートに存在していないこともあります。 そのような場合は、ビルド処理において対象ファイルを探しにいくパスを指定します。

ビルドコンテキスト は、ビルドに必要となるファイルへのパスのことであり、リポジトリのルートからの相対パスとして表わされます。 そのようなファイルパスを Build context（ビルドコンテキスト）欄に入力します。 ビルドコンテキストとしてソースコードリポジトリのルートを設定する場合には/を入力します。

メモ

Build context 欄のデフォルトパス/を削除して、そのまま空欄にすると、ビルド処理では Dockerfile へのパスをビルドコンテキストとして用います。 ただし混乱を避けるため、完全なパス指定を行うことをお勧めします。

Dockerfile location（Dockerfile の場所）では、ビルドコンテキストへの相対パスを指定します。 Dockerfile がビルドコンテキストパスのルートに存在する場合は、Dockerfile のパスは/のままとします。 （ビルドコンテキストが空欄であった場合 Dockerfile は、ソースリポジトリのルートからのパスを指定してください。）

正規表現と自動ビルド

ビルド指定においては正規表現（regex）を用いて、合致したブランチまたはタグのみをビルドすることができます。 また正規表現で得られた結果を使って、ビルドイメージに適用される Docker タグを生成することもできます。

ビルドソースを指定する際の正規表現において、グループ指定（カッコでくくった表現）は 9 個まで利用することができます。 そのグループに対する参照方法は、Docker Tag（Docker タグ）欄において{\1}から{\9}を使って行います。

BuildKit を用いたイメージビルド

自動ビルドは、デフォルトで BuildKit ビルドシステムを利用します。 かつての Docker ビルドシステムを利用したい場合は、環境変数 DOCKER_BUILDKIT=0 を設定します。 BuildKit に関する詳細は BuildKit を使ったイメージビルド を参照してください。

プライベートサブモジュールをリンクしているリポジトリのビルド

Docker Hub ではデプロイ鍵をソースコードリポジトリ内において設定することが可能であり、リポジトリのクローンやそのビルドを可能にしています。 ただしこの鍵は、単一の特定コードリポジトリに対してしか動作しません。 ソースコードリポジトリにおいてプライベート Git サブモジュールを利用している場合（あるいはビルドにあたっては別のプライベートリポジトリをクローンする必要がある場合）、Docker Hub はそのような追加のリポジトリにアクセスすることができません。 そのためビルドが成功せず、ビルドタイムラインにエラーログが出力されます。

これを回避するには、自動ビルドにおいて環境変数SSH_PRIVATEを利用します。 これによってデプロイ鍵をオーバーライドして Docker Hub によるビルド処理が他のリポジトリにアクセスできるようにします。

メモ

自動ビルドをチーム内で利用している場合は、代わりに 以下の手順 に従って、ソースコードプロバイダーに対するサービスユーザーを設定してください。 これは個々のアカウントに対して Docker Hub からソースリポジトリに対するアクセスを制限することでも実現することができます。

1. ビルド目的でのみ利用する SSH 鍵ペアを生成します。 そしてその公開鍵をソースコードプロバイダーのアカウントに追加します。

   この手順は任意です。 ただしこれを行っておけば、ビルド専用の鍵を削除しても、別のアクセスまで削除する必要がなくなります。

2. プライベート鍵をクリップボードにコピーします。
3. Docker Hub において、プライベートサブモジュールへのリンクを持つリポジトリのビルドページにアクセスします。 （必要であれば ここ に示す手順に従って自動ビルドの設定を行います。）
4. 画面下段にある Build Environment variables（環境変数のビルド）の横のプラス記号（+）をクリックします。
5. 新たな環境変数の名前としてSSH_PRIVATEを入力します。
6. プライベート鍵を Value（値）欄に貼り付けます。
7. Save をクリックします。 または Save and build をクリックして、ビルドが成功することを確認します。

メモ

git clone を使ってプライベートサブモジュールを設定する際には、HTTPS 経由ではなく SSH 経由（git@submodule.tld:some-submodule.git）としなければなりません。

チーム向けの自動ビルド

自分のアカウント名前空間内において自動ビルドリポジトリを生成すれば、そのリポジトリ内での自動ビルドの起動、キャンセル、再ビルド、編集、削除は思いのままです。

Docker Hub のチームリポジトリに対しての同じ操作は、組織のOwners（所有者）チームのメンバーであれば可能になります。 write（書き込み）権限を持つチームメンバーであれば、チームリポジトリにおいてビルドの起動、キャンセル、再ビルドが可能になります。 しかしチームリポジトリ設定を書き換えたり、チームリポジトリそのものを削除したりすることはできません。 read（読み込み）権限を持つユーザーアカウントである、あるいはread権限を持つチームメンバーである場合は、ビルド設定やテスト設定の内容を参照することができます。

チーム自動ビルドに対するサービスユーザー

メモ

チームに対する自動ビルドの設定は、Owners（所有者）チームのメンバーのみが行うことができます。

チームに対して自動ビルドの設定を行う際には、Docker Hub からソースコードリポジトリへのアクセスを許可するために、特定のユーザーアカウントに紐づいた OAuth を利用します。 これによって Docker Hub からは、リンクされたソースプロバイダーのアカウントがアクセス可能なものすべてにアクセスできるようになります。

組織やチームにおいては、ソースプロバイダーへのアクセスを許可するために、専用のサービスアカウント（言い換えると「マシンユーザー」）を生成することをお勧めします。 これを行っておけば、個別ユーザーのアクセス権限が変更されても、ビルドが失敗することがなくなります。 しかもそのユーザーの個人的なプロジェクトは、組織全体に公開せずに済みます。

このサービスアカウントは、ビルドするリポジトリすべてに対してアクセス可能でなければなりません。 そしてソースコードリポジトリに対して管理権限を有していて、そのデプロイ鍵を管理できることが必要です。 必要であればこのアカウントの権限を制限して、特定のビルドに対して必要となる特定のリポジトリのみにアクセスするようにすることもできます。

プライベートサブモジュール（プライベート依存パッケージ）にリンクされたリポジトリをビルドしている際には、環境変数SSH_PRIVATEをオーバーライドして、そのアカウントに関連づいた自動ビルドを行う必要があります。

1. ソースプロバイダー上においてサービスユーザーを生成します。 そしてこれに対する SSH 鍵を生成します。
2. 組織内に「ビルド」チームを生成します。

3. ビルド対象とするリポジトリやサブモジュールに対して、この新たな「ビルド」チームがアクセスできるようにします。

   リポジトリの Settings（設定）ページにアクセスします。 GitHub では Collaborators and Teams（協力者とチーム）の一覧に新たな「ビルド」チームを追加します。 Bitbucket では Access management（アクセス管理）画面において、承認ｓれたユーザーの一覧に「ビルド」チームを追加します。

4. ソースプロバイダーの「ビルド」チームに対してサービスユーザーを追加します。

5. Docker Hub に対してOwners（所有者）チームのメンバーとしてログインします。 そして組織に切り替えて、サービスアカウントを使った ソースコードリポジトリへのリンク の手順を行います。

   メモ

   サービスアカウントへのリンクを生成するためには、ソースコードプロバイダー上の個人アカウントからログアウトすることが必要かもしれません。

6. 任意の作業として、生成した SSH 鍵を使ってプライベートサブモジュールを利用するビルドの設定を行います。 その際にはサービスアカウントを用いて 上の手順 に従います。

次に読むものは

ビルド処理のカスタマイズ

自動ビルドをカスタマイズするために、高度なオプションも用意されています。 たとえばユーティリティー環境変数、フック、ビルド時のオーバーライドなどです。 詳しくは 自動ビルドおよび自動テストのための高度なオプション を参照してください。

自動テストの追加

イメージがプッシュされるまえにコードのテストを行うには、Docker Hub の 自動テスト 機能を利用します。 これは自動ビルドや自動デプロイとシームレスに連携しています。

メモ

自動テストからビルドされるイメージはテスト目的に限られます。 したがってビルドされたイメージは Docker Hub にはプッシュされません。