Docker Hub の Source API ってなんだろう？

微妙に昨日の話（Docker Hub の Build triggers の使い方）に関連した内容になります。Build triggersとは別件で、shields.ioを使ってDockerイメージをAutomated Buildsを使っていることを示すバッジを表示しようと思ったのですが、ここを見ると「Docker Automated build」と「Docker Cloud Automated build」の2つがあって、さてどっちを使うべきなんだろう？と

先に結論を書くと後者の「Docker Cloud Automated build」バッジの方が新しく、最近ビルドしたものであればこちらを使います。2019年1月のInfoQの記事「新しいDocker HubがDocker CloudとDocker Storeを統合」によると、Docker Hubエクスペリエンスリリース時に新しい「自動ビルドプロセス」が提供されており、以前のものは「クラシック自動ビルド」と呼ばれているそうです。つまり古い「Docker Automated build」のバッジはクラシック自動ビルド用だと思います。

古い「Docker Automated build」のバッジを使用すると（新しい）Automated Buildsを使用していてもDocker API（curl https://registry.hub.docker.com/v2/repositories/イメージ名）のレスポンスはis_automatedがtrueにはなりません。（参考 Docker build shield show "manual" instead of "automated"?）同様にdocker searchでもAUTOMATEDはOKになりません。Docker APIはクラシック自動ビルドの情報を参照しているようです。

では新しい「Docker Cloud Automated build」のバッジはどの情報を参照しているのでしょうか？shields.ioの新しいAutomated Buildsへの対応の修正「feat: [DockerCloud] and automated. 」から https://hub.docker.com/api/build/v1/source/?image=イメージ名 というURLを発見しました。Build triggersと同じAPIのようです。

そこで試しにクエリーパラメータをつけずにGETしてみた所、以下のエラーメッセージが返ってきました。

$ curl -sS https://hub.docker.com/api/build/v1/source/ | jq
{
  "error": "Source API list view needs an image to filter"
}

どうやらこのAPIは Source API と呼ばれているようです。

クエリーパラメータimageを指定した場合のレスポンスは以下のようになります。Automated Buildsの設定が取得できました。この内容はイメージ名さえ分かれば誰でも認証なしに取得できるので秘密情報ではありません。（deploykeyが少し気になりますが、認証なしの場合は常に空になっているようです。）

$ curl -sS https://hub.docker.com/api/build/v1/source/?image=shellspec/openwrt | jq .
{
  "meta": {
    "limit": 25,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 1
  },
  "objects": [
    {
      "autotests": "SOURCE_AND_FORKS",
      "build_in_farm": true,
      "build_settings": [
        "/api/build/v1/setting/8c416bda-1599-430a-bf05-3cee4d58ed78/",
        "/api/build/v1/setting/e4128afa-03dc-44d7-8fa9-80ce78163874/"
      ],
      "channel": "Stable",
      "deploykey": "",
      "image": "shellspec/openwrt",
      "owner": "shellspec",
      "provider": "Github",
      "repo_links": false,
      "repository": "openwrt-docker",
      "resource_uri": "/api/build/v1/source/0312d9d5-8f97-4274-9594-2b3a80b0d3e3/",
      "state": "Success",
      "uuid": "0312d9d5-8f97-4274-9594-2b3a80b0d3e3"
    }
  ]
}

改めて、昨日作成した Build triggers のエンドポイントを見てみると以下のような形式でした。

https://hub.docker.com/api/build/v1/source/0312d9d5-(略)/trigger/a3(秘密)86/call/

つまり最初の0312d9d5-で始まる部分は（プロジェクトを示す）uuidで、秘密情報ではないことがわかります。2番目の(秘密)の部分がTrigger Tokenなのでしょう。

他に Source API にどんなものがあるか、GitHubで探してみましたが、Automated BuildsとBuild triggers以外の使用例は見つかりませんでした。Docker Hubでも正式にドキュメント化はされてないようです。（私が見つけられなかっただけかもしれませんが）