GitHub Packages Container Registryをモデリングしてみた – UMLを理解の道具として

コンテナイメージのコンテナレジストリとしてGitHub Packages Container Registryを使っていますが、コンテナイメージとリポジトリの関係やコンテナイメージ登録時の初期設定などが直観的でなく毎回？となるため、理解の整理と今後の備忘を兼ねGitHub Packages Container Registryの構造とコンテナイメージ登録時の挙動に関係する者たちをUMLでモデリングしてみました。今回はこのモデルを使ったGitHub Packages Container Registryの説明に加えて日ごろ筆者がどのような感じでUMLを使っているかも少し触れてみたいと思います。

まずはContainer Registryがどこでどのようにコンテナイメージを管理しているかの関係をモデルにしたものが次のクラス図になります。

(クリックすると拡大します)

クラス図だけを見てもモデルの意図を読み切れないと思うため、このモデルに対する補足を文章で加えると次のようになります。

• コンテナイメージとAccountとの関係

  • コンテナイメージを管理するContainerRegistryはPersonalアカウントまたはOrganizationアカウントごとに1つ存在する。
  • ImageIDを持つコンテナイメージの実体(Image)はそのイメージ名(ImageName)ごとに集約され ContainerRegistryによって管理される。
  • よって、コンテナイメージ(Image)とAccountの関係は常に存在する。
  • また、それぞれのクラスの具体例を示すとImageIDがba877dcd60adのコンテナイメージ(Image)に対してextact-io/hello-world:latestの(Dockerでいうところの)イメージ名とタグが付けられていた場合、extact-ioがAccount,hello-worldがImageName,latestがTagのインスタンスとなる。
    
    

• コンテナイメージとRepositoryとの関係

  • コンテナイメージ(Image)とRepositoryの間に直接的な関係はないが、コンテナイメージからRepositoryへの行き来を可能にするショートカット的な関係(Connect)を1つ持つことができる。
  • このコンテナイメージとRepositoryとの関係は多重度に表されているように場合によっては存在しないこともある。
  • よって、コンテナイメージとRepositoryとの関係は常に存在するわけではなく、Accountとはこの点が異なる。なお、このConnectが作られる条件等は次のモデルで詳しく説明する。

コンテナイメージの管理のされ方が分かったところで、次のお題としてコンテナイメージ登録時の挙動を分析した結果が次のクラ図になります。このモデルで表したかったことはコンテナイメージ登録時に GitHub Packages により行われる初期設定とそれに関係するものとなります。

(クリックすると拡大します)

今回も先ほどと同じようにモデルに対する補足を文章で付けてみます。

• Permissionの種類とRepositoryとの関係
  • コンテナイメージの初回登録時にはコンテナイメージを集約する枠的なものとしてImageNameが作られる。
  • コンテナイメージの登録にはPermissionが必要となる。このPermissionにはPersonalアカウントごとに払い出されるPersonal Access Token(PAT)とRepositoryが払い出すGITHUB_TOKENの２つがある。
  • PATはAccount単位で払い出されるため、特定のRepositoryに紐づくものでなくAccountが持つすべてのRepositoryに対するものとなる。このためPATにRepositoryの色はない。
  • 一方のGITHUB_TOKENはRepository単位で払い出されるめ、GITHUB_TOKENで操作できるのはそれを払い出したRepositoryのみとなる。よって、GITHUB_TOKENが使われた場合、対象としているRepositoryを特定できる。

次に初回登録時の挙動を補足すると、以下に説明するとおり、その挙動は登録時に使われたPermissionと登録時のコンテナイメージのLABELの有無で変わってきます。

• Connectの作成(コンテナイメージとRepositoryとの紐づけ)
  • 初回登録時のPermissionにGITHUB_TOKENが使われた場合、GITHUB_TOKENを払い出したRepository、つまりGitHub Actionsのワークフローを実行しているRepositoryに対するConnectが作られる。
  • PATを使った場合でもコンテナイメージにorg.opencontainers.image.sourceのLABEL(OCIではAnnotation)^[1]が設定されている場合は、そのvalueに設定されているRepositoryに対するConnectが作られる。
  • 上記の条件に当てはまらず初回登録時にConnectが作成されなかった場合でも画面から手動で任意のRepositoryに対するConnectを作成することができる。
  • ただし、1度作られたConnectは削除することはできない。これはコンテナイメージとRepositoryの関係を1度設定した後はその関係を変えることができないことを意味する。
    
    

• 可視性の初期設定
  • コンテナイメージは公開(PUBLIC) / 非公開(PRIVATE)の可視性を持つが、この可視性は初回登録時のPermissionにより決定される。
  • 登録時にGITHUB_TOKENが使われた場合、そのGITHUB_TOKENのRepositoryと同じ可視性がコンテナイメージに初期設定される。つまり、GITHUB_TOKENを使ってGitHub Actionsのワークフローでコンテナイメージを初回登録した場合、そのワークフローを実行したリポジトリと同じ可視性が設定される。
  • 一方のPATが使われた場合、GitHub Packagesはどちらの可視性にすればよいか判断がつかないため、初期設定として非公開(PRIVATE)が設定される。
  • なお、可視性はConnectとは異なりいつでも変更が可能となっている。

モデルをもとに説明を読むと意外とスッと理解していただけたのではないでしょうか？

設計成果物としてUMLを使う機会は以前よりも少なくなりましたが、筆者が所属する豆蔵では「こんな感じ」と設計意図を伝えるコミュニケーション手段としてUMLは今でも身近に使われています。

UMLやモデリングというと敷居が高そうな感じがしますが、誤解を恐れずに言うとコミュニケーションの道具として使う分には細かいことに拘る必要はありません。たとえ荒削りの図でもコミュニケーションの手助けとしては十分効果を発揮してくれます。
なので、UMLに慣れていないメンバーには、UMLとしてではなくまずは説明の"図"として使っていくとそのうちに自然に使えるようになると思うよと筆者はアドバイスしています。

もしUMLはなぁ～と思われている方がいたらコレを機会にまずはコミュニケーションの道具としてUMLを使い始めてみてはいかがでしょうか？令和の時代になってもUMLはお勧めです！