Redmine Mirror¶

Import and synchronize projects between Redmine instances!

Digest¶

Redmine Mirror provides modular project import and asynchronous synchronization between Redmine instances.

Designed for migrating projects to a new instance and maintaining regularly updated secondary copies. Each destination project has its own source connection, reference mappings and synchronization schedule.

Synchronization is one-way, from source to destination. Source deletions are not propagated.

Features¶

• Preview before applying changes
• Manual execution and automatic scheduling
• Project-specific reference mappings
• User mapping and anonymization
• Filtered execution logs and progress tracking
• Local modification detection and conflict handling
• Pending cross-project relations and parent links
• Extensible adapters for additional modules

Supported modules¶

• Issues, including privacy, mapped authors and historical dates
• Time entries
• Issue categories and project versions
• Notes, private notes and supported historical field changes
• Issue attachments
• Relations between issues
• Parent and child issue links
• Watchers
• Custom field values and supported historical changes

User accounts and custom field definitions must already exist on the destination instance.

Localisations¶

• English
• French

Development status¶

Current development version: 0.1.0-dev.

Database-backed and browser tests currently cover Redmine 6.1.4 with SQLite. Other versions and databases have not yet been validated.

Wiki, project files, SLA and Reporting adapters are not yet implemented.

Mirror maintains a secondary copy of selected accessible data. It does not replace complete database and file backups.

Credits¶

Icons created by Magnific on Flaticon.

License¶

GPL-2.0-or-later. Third-party artwork retains its own license.

Requirements¶

• Install Mirror on the destination instance only.
• Enable REST APIs on both instances and use HTTPS URLs.
• Provide source API access to the required data.
• Provide destination API permissions for issue and time-entry writes.
• Configure Redmine's database_cipher_key before storing the source API key.
• The worker must share the destination database, attachment storage and cipher key with the web application.

Installation¶

Back up the destination database and attachment storage.

1. Copy the plugin directory into plugins/redmine_mirror.
2. From the Redmine root, run the migration command below.
3. Restart Redmine.
4. Create or select the destination project and enable Mirror in Settings → Modules.
5. Grant view_mirror and manage_mirror to the appropriate roles.
6. As an administrator, configure the source URL, numeric project ID, API key and selected modules under Mirror → Connection.
7. Configure reference mappings under Modules and mappings.
8. Configure the worker as described below.
9. Run a preview, review its results, then start synchronization.

RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_mirror

Required local users, trackers, statuses, priorities, activities and custom field definitions must already exist. Administrators create custom fields; project managers can map or ignore them.

Connection configuration, module selection and source catalogue refresh require administrator privileges.

Worker and scheduling¶

Set MIRROR_DESTINATION_URL and MIRROR_DESTINATION_API_KEY in the worker's environment through your service configuration or secret manager.

Run the following command periodically, for example every minute using cron or a systemd timer:

RAILS_ENV=production bundle exec rake redmine_mirror:tick

The worker processes both manual requests and scheduled synchronizations. Without it, requests remain queued.

Automatic synchronization is disabled by default. Configure each project's interval in the Synchronization tab.

Supported intervals: 5, 15, 30, 60, 360 and 1440 minutes.

Cross-project links¶

Projects synchronize independently. Import cross-project targets first, then rerun projects containing their relations or parent links.

Unresolved links remain visible in the corresponding module tab.

Upgrading¶

1. Back up the database, attachment storage and installed plugin.
2. Stop web and worker processes.
3. Replace the plugin files.
4. Run the installation migration command above.
5. Restart both processes and check a preview.

When reverting a schema change, restore the matching database, files and plugin together.

Important limitations¶

• Data hidden from the source API account is not imported.
• Source deletions are not propagated.
• Imports are not atomic across API calls; successful writes remain after an error.
• Local modifications require explicit conflict handling; no forced overwrite is provided.
• Keep complete database and file backups alongside Mirror synchronization.