はじめに

Redmine 6.1（Rails 7.2系）の検証環境構築に続き、今回は各種UI拡張やマクロ機能の土台となる Additionals および Additional Tags プラグインを導入しました。

依存関係の親玉とも言えるこの2つのプラグインですが、最新版（main ブランチ）をそのままクローンしてマイグレーションを実行したところ、複数の予期せぬエラーに遭遇しました。

今回は、遭遇した3つのトラブルと、それを解決して Redmine 6.1 上で正常認識させるまでのメモです。

今回の前提条件

  • Redmine: 6.1.4.stable (Rails 7.2.3.2)
  • Ruby: 3.2.x
  • 対象プラグイン:
  • additionals (AlphaNodes製 / 共通ライブラリ)
  • additional_tags (AlphaNodes製 / タグ機能拡張)

遭遇した3つの罠と対処法

罠1: 最新版が「Redmine 7.0以上」を要求して abort

GitHubから main ブランチをそのままクローンしてマイグレーションを実行したところ、以下のエラーが発生しました。

Redmine::PluginRequirementError: additional_tags plugin requires Redmine 7.0 or higher but current is 6.1.4.stable.25001
  • 原因: リポジトリ先端（main）の開発が既に次世代の Redmine 7.0 / Rails 8系 向けに進んでおり、6.1環境が弾かれていました。
    • 対処: Redmine 6.x に対応している安定版タグ（v3.4.0 など）へチェックアウトを切り替えます。

罠2: Gitの「dubious ownership」セキュリティエラー

sudo -u www-data git checkout を実行した際、Git のセキュリティ機構（所有権チェック）に阻まれました。

fatal: detected dubious ownership in repository at '/home/www-data/redmine_v6/plugins/additionals'
  • 原因: 実行ユーザーとディレクトリ所有者（www-data）の不一致による安全装置の作動。
    • 対処: www-data ユーザーの Git グローバル設定にセーフディレクトリを登録して回避しました。
sudo -u www-data git config --global --add safe.directory '*'

罠3: プラグイン依存 Gem の未調合（Could not find compatible versions）

タグを切り替えて rake redmine:plugins:migrate を実行したところ、今度は Bundler が停止しました。

Because every version of additionals depends on render_async >= 0
  and render_async >= 0 could not be found in locally installed gems,
  additionals cannot be used.
  • 原因: プラグインが要求する Gem（render_async 等）が、ローカルの vendor/bundle にインストールされていませんでした。
    • 対処: マイグレーション前に必ず bundle install を通す必要があります。

成功した導入手順まとめ

1. リポジトリのクローンと安全設定

  • Redmine(検証用)ルートディレクトリに移動
cd /home/www-data/redmine_v6/plugins
  • プラグインのgit clone
sudo -u www-data git clone https://github.com/alphanodes/additionals.git
sudo -u www-data git clone https://github.com/alphanodes/additional_tags.git
  • Git 所有権警告の解除
sudo -u www-data git config --global --add safe.directory '*'

2. Redmine 6.x 対応タグへのチェックアウト

  • additionalsでチェックアウト
cd /home/www-data/redmine_v6/plugins/additionals
sudo -u www-data git checkout $(sudo -u www-data git tag -l | grep -E '^v?3\.' | tail -n 1)
  • additional_tagsでチェックアウト
cd /home/www-data/redmine_v6/plugins/additional_tags

```bash
sudo -u www-data git checkout $(sudo -u www-data git tag -l | grep -E '^v?3\.' | tail -n 1)

3. 依存 Gem のローカルインストール（最重要）

cd /home/www-data/redmine_v6
sudo -u www-data bundle install

4. マイグレーションと再起動

sudo -u www-data bundle exec rake redmine:plugins:migrate RAILS_ENV=production
sudo -u www-data bundle exec rake assets:precompile RAILS_ENV=production

おわりに

構築中のRedmine 6.1サイトにアクセスし、管理画面（/admin/plugins）を開くと、Additional Tags (3.4.0) と Additionals (3.4.0) が無事に認識され、エラーなく設定画面を開くことができました。

プラグイン導入時は、「最新ブランチを追うのではなく適切なリリースバージョン（タグ）を選ぶこと」と「DBマイグレーションの前に bundle install で Gem 依存を揃えること」が鉄則であると再認識させられた検証でした。