aquaの利用メモ¶

Added in version 2025.8.10.

個人的なaqua利用時のメモ。

aquaとは¶

課題

後で書くかも？

利用者目線での評価¶

asdfやmiseあたりと同じく、ツールチェイン類を「横断的に保管して」「プロジェクト単位で細かくバージョン調整できる」のが便利。それに加えて、「レジストリにないCLIの管理」も比較的容易なのがありがたかった。 [1] [2]

Renovateのカスタムマネージャーも提供してくれているので、トータルでの導入も容易と考えている。

なお、使ってみた感じでは「CLIツール自体の管理」に役割を限定させている。そのため、「uv自体の管理」はするが「uvの内部とのシームレスな連携」は管轄外となっている。 Pythonツールチェインはuvがかなり支配的になっているため困ることはあまりないのだが、 Node系だとどうするかが悩みどころとなる（特にpnpmを使用しているケース）。 [3]

とはいえ、条件が成立する範囲においてはカバー可能な領域はかなり広いので、次のような使いわけをしておくと良さそうではある。

プロジェクト内の採用言語を前提とするツール群は、各パッケージマネージャーで管理する。
Lefthookやuvのような「プロジェクトの進行に必要なもの」は、プロジェクトのaqua.yamlで管理する。
GitHub CLIやghqのような「プロジェクトを横断的に管理するもの」や、NeoVimのような「プロジェクトの直接的に関わらないもの」は、グローバルなaqua.yamlで管理する。
Git自体のようなCLIとはいえそれ自体で完結しないものは、OSのパッケージマネージャーで管理する。

セットアップ¶

ローカルマシンへのインストール¶

ローカルマシンへのインストールは、基本的にドキュメントに従うだけでよい。 OSに合わせたインストール手続きを取れば、割とあっさり使用可能になる。

https://aquaproj.github.io/docs/install

特にLinux環境下の場合、環境変数の調整が必要になるためログインシェル向けの調整は忘れないでおきたい。

共通CLIの導入¶

ユーザーのホームディレクトリに aqua.yaml があればそれを参照してくれるようにはなっている。

ただし、自分の場合は dotfiles を利用して、こちらをグローバル設定として管理している。メリットは「カスタムレジストリ周りの管理も比較的楽」「 git pull からの aqua i で最新化がすぐ可能」といったあたり。

プロジェクトへの組み込み¶

ここから先はローカルマシンへのインストールが終わっていることが前提のため、普通に aqua コマンドを使っていく形となる。

プロジェクトは、GitHubリポジトリ上に「GitHub Actionsによるワークフロー実行」「Renovateによる適宜更新」の導入を前提としている。

aqua.yaml¶

aqua g -i などを使って普通に編集する。オフィシャルのレジストリにないツールをどうしても使いたい場合は、ちょっと頑張ってカスタムレジストリを用意しておくと良い。

renovate.json / renovate.json5¶

オフィシャルでカスタムマネージャーを提供してくているので、有効化してしまったほうが良い。これを導入すると「aqua.yaml内で管理しているツールのバージョン」はRenovateが適宜追いかけてくれるようになる。

ただし、ツール数が増えれば増えるほどPR数が増えてくるので、可能な限り automerge は全体で true にしておくことが望ましい。

なお、 "automerge": true にするといくつかの条件下で不都合が起こるので、適宜 packageRules で無効化してやるとよい。自分の場合だと、Pythonライブラリの開発をすることが多いので、サポート下限値で設定している .python-version [4] はモニタリング自体をさせていない。

.github 配下¶

大雑把に書くと、 actions/checkout のuses直後に aquaproj/aqua-installer をusesするだけ。下記が例となる。

jobs:
  a-job:
    steps:
      - uses: actions/checkout@v4
      - uses: aquaproj/aqua-installer@d1fe50798dbadd4eb5b98957290ca175f6b4870f # v4.0.2
        with:
          aqua_version: v2.51.2

aquaはCLIの遅延インストールができるので、この設定にしておけば「aqua本体をとりあえずセットアップして、後続ステップで必要な時にダウンロードする」が簡単に実現できる。

なお、aquaのバージョンやアクションのハッシュはRenovateによって適当に管理してもらえばよい。

注記