• Home
  • Case Story: Full Migration from Redmine to GitLab

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

  1. 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.
  2. 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.
  3. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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

ChallengeDescriptionResolution
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 & AttachmentsEnsuring 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 & PermissionsRedmine’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 ReposActive 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 DataHistorical 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.

5. Outcomes & Best Practices

  • Consolidated DevOps Environment: GitLab’s integrated CI/CD and Issue Board replaced multiple Redmine plugins.
  • Improved Collaboration: A single platform for code, issues, and wiki streamlined communication across teams.
  • Successful User Adoption: Minimal friction for developers thanks to thorough planning and training materials.
  • Enhanced Project Visibility: GitLab’s built-in analytics and reporting tools offered improved project insights.

Key Takeaways:

  1. Pilot Migrations
    Always test the approach on a small subset of data to refine scripts and identify pitfalls.
  2. Role-Mapping Exercises
    Thoroughly document how Redmine roles map to GitLab roles to prevent permission-related bottlenecks or security gaps.
  3. Data Integrity Checks
    Script-driven verifications and manual spot checks are vital for ensuring no issues or attachments are lost or corrupted.
  4. Technical & User Training
    Provide detailed guides to users on new workflows, especially how wiki formatting may differ in GitLab.
  5. 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 planningcareful 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.