vltをGithub Actionsで使って依存ライブラリをインストールする

最近JSのパッケージマネージャ「vlt」をGithub Actionsで使用する際に、セットアップから認証、ロックファイル同期まで数々の課題に直面しました。その解決方法と得られた知見を共有します。

2026.09.01

こんばんは、情報システム室の夏目です。
最近JSのパッケージマネージャとして vlt を使っているのですが、Github ActionsなどCI/CD環境で使うときに少し苦労したことがあるので共有します。
 Github Actionsでvltをインストールするjobs: 
  vlt_install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: v26
      - uses: vltpkg/setup-vlt@v1
vltpkg/setup-vlt というアクションを使用してインストールします。
ドキュメント上では Fast installation via npm global install と書いてありますが、内部的には npm install -g vlt をしていました。
https://github.com/vltpkg/setup-vlt/blob/main/src/setup.ts#L100-L115
そのため、vltをインストールする前にnodeのセットアップを行う方が良さそうです。

vltを動かすnodeのバージョンが変わるので。
先にnodeのセットアップをした場合
後でnodeのセットアップをした場合
前者では actions/setup-node でインストールしたnodeの配下にあるのがわかりますが、後者では元々入っているnodeにインストールされているのがわかります。
 苦労したこと今回はデフォルトに近い動作を確認するため、vltのリポジトリからnpmパケージをインストールしようとしてみました。
しかし二つほど苦労したことがありました。
 Github Actions上でvlt install できないセットアップまでは問題なくできたのですが、実際に依存ライブラリをインストールする際にエラーが出てインストールできませんでした。
認証がうまくいっていないというものです。

Github Actionsに関わらずCI/CDで非常に困ることです。
公式ドキュメント (Authentication - CI (and Other Headless Environments)) を見ると VLT_TOKEN という環境変数にトークンを渡せと書かれています。
https://docs.vlt.sh/cli/auth#ci-and-other-headless-environments
このときvltの設定は次のようにしていました。

(プロジェクトルートに vlt.json を置くことでプロジェクトレベルの設定ができる)
vlt.json
{
  "config": {
    "registries": {
      "npm": "https://registry.vlt.io/sinofseven/npm/"
    },
    "default-registry-alias": "npm"
  }
}
npmパッケージのインストールはvltのミラーリポジトリを使用するようにして、デフォルトで使用するエイリアスはnpmを使用するように私は書いていました。
 解決方法実はこの書き方としてはデフォルトリポジトリの設定としては足りていないようで、次のように書いたら解決しました。
vlt.json
{
  "config": {
    "registries": {
      "npm": "https://registry.vlt.io/sinofseven/npm/"
    },
    "default-registry-alias": "npm",
    "registry": "https://registry.vlt.io/sinofseven/npm/"
  }
}
デフォルトリポジトリというのは default-registry-alias ではなく registry を指していたようです。
また、このときでも config.registries.npm のキーは必須のようです。

指定していなければ次のエラーがでました。
 検証できなかったことちなみに、ドキュメントにあったレジストリ毎のトークンを指定する VLT_TOKEN_xxx 環境変数はうまくいきませんでした。
VLT_TOKEN_https_my_custom_registry_mycompany_local="helloworldtokendeadbeef" vlt install
今はvlt.jsonに registry キーを設定するのが良さそうです。
 vlt ci に失敗するvlt install ではロックファイルを更新してしまうので、CI/CDは vlt ci を使うことが一般的かと思います。

色々試しているときに vlt ci に失敗することがありました。
$ vlt ci
resolving dependencies > extracting files
Error: Lockfile is out of sync with package.json. Run "vlt install" to update.
  Configuration options have changed (e.g. modifiers, registries, catalogs)

Full details written to: /Users/user/Library/Application Support/vlt/error-logs/error-60447.log

Open an issue with the full error details at:
  https://github.com/vltpkg/vltpkg/issues/new
このとき、vlt.jsonは色々弄っていましたが package.jsonは一切弄っていなかったので最初はよくわかりませんでした。

エラーメッセージを良く見ると Configuration options have changed (e.g. modifiers, registries, catalogs) とあり、vlt.jsonで設定を変更したことに影響を受けたようです。
ロックファイルを見ると生成時のオプションの値が残っています。
vlt-lock.json
{
  "lockfileVersion": 1,
  "options": {
    "registry": "https://registry.vlt.io/sinofseven/npm/",
    "registries": {
      "npm": "https://registry.vlt.io/sinofseven/npm/"
    }
  },
  "nodes": { ... },
  "edges": { ... }
}
実際、ロックファイルに合わせて vlt.json の設定を変更したら問題なく vlt ci が動くようになりました。
なので、CI/CDに使う場合には vlt install したときの設定値は vlt.json できちんと管理する必要がありそうです。
 まとめ以上、vltをGithub Actionsで動かしてみた話でした。
何かのお役に立てたら幸いです。