Our team recently executed a comprehensive migration from Redmine to GitLab, transferring all data—including Git repositories, issues, user accounts, and wiki pages. The primary aim was to consolidate project management and source code in a single, modern DevOps platform without disrupting ongoing development workflows.
1. Planning & Requirements
Scope & Data Identification
Repositories: Multiple Git repositories versioned within Redmine.
Issues & Tickets: Thousands of open and closed issues, custom fields, and attachments.
Users & Permissions: Existing Redmine user roles and permissions had to map accurately to GitLab’s role models.
Wiki Pages & Documentation: Redmine’s built-in wiki was actively used for project documentation.
Migration Objectives
Data Integrity: All issues, comments, attachments, and history to be preserved accurately.
Minimal Downtime: Developers needed continuous access to source code while the migration took place.
User Access Continuity: Seamless transition for users, preserving credentials, permissions, and accountability.
Consolidated Platform: Utilize GitLab’s integrated CI/CD, issue tracking, and wiki.
Timeline & Communication
Pre-Migration Announcement: Shared timeline with developers, specifying feature freeze windows if needed.
Pilot Test: Migrated a small “test” project first to validate the approach.
Final Migration: Planned cutover for a weekend to minimize impact.
2. Tools & Approaches
Built-in GitLab Importers vs. Custom Scripts
GitLab offers partial importers for repositories and some Redmine data, but not always 100% coverage.
Custom Scripting was required to handle specific fields, attachments, wiki structure, and user mapping.
Automated Data Extraction
Redmine REST API and direct database queries for issues, comments, wiki text, and attachments.
Git Repositories cloned locally to verify integrity, then pushed to GitLab.
Role & Permission Mapping
Redmine’s roles (e.g., Manager, Developer, Reporter) were mapped to GitLab’s role system (e.g., Maintainer, Developer, Reporter, Guest).
Verified that GitLab’s more granular permissions aligned with existing project-level roles in Redmine.
Wiki & Documentation Conversion
Markdown vs. Textile: Redmine uses Textile formatting, while GitLab supports Markdown by default.
Automatic Converters were tested to ensure wiki formatting translated accurately.
Manual Edits were done for complex, custom-formatted pages.
3. Implementation Steps
Pilot Migration on Test Project
Repository Import: Simple push to GitLab remote.
Issues & Comments: Exported from Redmine and imported via custom script to GitLab’s Issue API.
Wiki Conversion: Checked for formatting discrepancies.
User Account Mapping: Resolved email collisions and verified login methods.
Data Cleanup & Standardization
Archived Old Issues: Cleaned up historical tickets no longer relevant.
User Reconciliation: Ensured consistent names, emails, and roles across both platforms.
File Attachments: Moved to GitLab’s structure and verified file integrity.
Production Migration
Scheduled Downtime: A short window to freeze Redmine updates and ensure no data changes mid-migration.
Automated Scripts: Extracted and transferred issues, comments, wiki pages, attachments in batches, validating each batch for correctness.
Repository Switchover: Updated remote origin from Redmine’s Git URLs to GitLab, ensuring minimal interruption for developers.
Verification & Final Cutover
Data Checks: Confirmed total issues matched, all attachments were visible, and wiki pages rendered correctly.
User Acceptance Testing: Key stakeholders confirmed they could access projects and found their data intact.
Decommissioning Old Tools: Kept Redmine in read-only mode for a short grace period before full shutdown.
4. Challenges & How We Addressed Them
Challenge
Description
Resolution
1. Mixed Data Formats (Textile/Markdown)
Redmine uses Textile while GitLab uses Markdown.
– Developed an automated conversion script for wiki pages. – Performed manual edits on especially complex or custom-formatted pages.
2. Preserving Issue History & Attachments
Ensuring all comments, timestamps, and file attachments were migrated without corruption or loss.
– Utilized Redmine REST API + direct DB queries for comprehensive data extraction. – Performed integrity checks on large file sets.
3. User Authentication & Permissions
Redmine’s user roles differ from GitLab’s role structure, causing confusion and potential security gaps.
– Mapped roles carefully, verified with small test groups. – Consolidated user accounts under consistent naming and single sign-on.
4. Managing Downtime for Git Repos
Active developers required near-zero downtime for their repositories.
– Adopted a staged approach—cloned repos in advance. – Planned a short freeze window to reassign Git remotes.
5. Large-Scale Legacy Data
Historical issues spanning multiple years, with references to old attachments and external links.
– Archived obsolete issues before migration. – Created redirection or notes for external references no longer valid in GitLab.
Pilot Migrations Always test the approach on a small subset of data to refine scripts and identify pitfalls.
Role-Mapping Exercises Thoroughly document how Redmine roles map to GitLab roles to prevent permission-related bottlenecks or security gaps.
Data Integrity Checks Script-driven verifications and manual spot checks are vital for ensuring no issues or attachments are lost or corrupted.
Technical & User Training Provide detailed guides to users on new workflows, especially how wiki formatting may differ in GitLab.
Contingency Planning Maintain read-only access to the old platform until you’re confident everything in GitLab is working as intended.
6. Conclusion
Migrating from Redmine to GitLab can significantly streamline and modernize your development process, but it requires thorough planning, careful execution, and robust data validation. By conducting a pilot, automating data extraction and transformation, and properly mapping user roles, our team achieved a smooth, fully documentedtransition.
Next Steps
Consider taking advantage of GitLab’s CI/CD features to automate testing and deployments.
Regularly review and clean up project data to keep the new environment organized and efficient.
Through this migration, we demonstrated that all facets of Redmine data—repos, issues, wikis, and more—can be successfully consolidated into a single GitLab instance, boosting collaboration and minimizing administrative overhead for ongoing project management.
Overview
Our team recently executed a comprehensive migration from Redmine to GitLab, transferring all data—including Git repositories, issues, user accounts, and wiki pages. The primary aim was to consolidate project management and source code in a single, modern DevOps platform without disrupting ongoing development workflows.
1. Planning & Requirements
2. Tools & Approaches
3. Implementation Steps
4. Challenges & How We Addressed Them
– Performed manual edits on especially complex or custom-formatted pages.
– Performed integrity checks on large file sets.
– Consolidated user accounts under consistent naming and single sign-on.
– Planned a short freeze window to reassign Git remotes.
– Created redirection or notes for external references no longer valid in GitLab.
5. Outcomes & Best Practices
Key Takeaways:
Always test the approach on a small subset of data to refine scripts and identify pitfalls.
Thoroughly document how Redmine roles map to GitLab roles to prevent permission-related bottlenecks or security gaps.
Script-driven verifications and manual spot checks are vital for ensuring no issues or attachments are lost or corrupted.
Provide detailed guides to users on new workflows, especially how wiki formatting may differ in GitLab.
Maintain read-only access to the old platform until you’re confident everything in GitLab is working as intended.
6. Conclusion
Migrating from Redmine to GitLab can significantly streamline and modernize your development process, but it requires thorough planning, careful execution, and robust data validation. By conducting a pilot, automating data extraction and transformation, and properly mapping user roles, our team achieved a smooth, fully documentedtransition.
Next Steps
Through this migration, we demonstrated that all facets of Redmine data—repos, issues, wikis, and more—can be successfully consolidated into a single GitLab instance, boosting collaboration and minimizing administrative overhead for ongoing project management.
Recent Posts
Recent Comments
About Me
Zulia Maron Duo
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore.
Popular Post
GitOps: DevOps with Version Control
2024-12-30Case Story: Large-Scale Migration from GitLab to
2024-08-30Case Story: Live Database Migration from Self-Hosted
2024-06-30Popular Categories
Archives