Migrating Dev Teams Off Microsoft 365 to LibreOffice + Git: A Practical Migration Plan

Beat the friction: why dev teams are ditching Microsoft 365 in 2026

Development and documentation teams face a common pain: fragmented collaboration when editors live in one ecosystem (Microsoft 365) and source and CI pipelines live in another (Git). That friction costs time, blocks automation, and complicates auditing. This migration playbook shows how to move teams to a LibreOffice + Git native workflow that preserves rich documents, restores privacy, enables CI/CD for docs, and treats documentation as first-class code.

At-a-glance migration plan (inverted pyramid)

• Goal: Replace Microsoft 365 editing and collaboration with LibreOffice for WYSIWYG artifacts and Git-first workflows for versioning and automation.
• Scope: Developer docs, design / spec docs, templates, internal policies, spreadsheets used for release automation, and presentation artifacts used in engineering reviews.
• Outcome: Text-first docs where possible (Markdown/AsciiDoc), ODF for LibreOffice-managed artifacts, CI pipelines that validate/convert/render, template governance, macro controls.

Why this is timely in 2026

Two trends make this migration practical now: advances in office-suite interoperability and the maturation of doc-as-code tooling. The LibreOffice 8.x era improved OOXML fidelity and headless conversion fidelity, and utilities like Pandoc and LibreOfficeKit integrate cleanly into CI containers. At the same time, organizations are more sensitive to data residency and AI data exposure—moving away from closed cloud editing can reduce risk and increase auditability.

High-level migration phases

1. Strategy & stakeholder alignment
2. Inventory & format assessment
3. Target formats and templates
4. Conversion & pilot
5. Git workflows & collaboration patterns
6. CI/CD integration and automation
7. Training, governance, and rollout

Phase 1 — Strategy & stakeholder alignment

Start by defining measurable success criteria and constraints. Example goals:

• Remove Microsoft 365 subscriptions for engineering and docs teams within 6 months.
• Have 90% of new documentation in text-first formats; remaining 10% in ODF templates.
• All official templates versioned in Git, signed and CI-validated.

Identify stakeholders: docs owners, release managers, security, IT (for desktop rollout), and SRE for CI pipelines. Capture must-haves (macros support? digital signing?) and deal-breakers (regulatory formats, archived PDFs).

Phase 2 — Inventory & format assessment

Scan repositories, shared drives and Microsoft 365 tenant exports to build an inventory. Key attributes to tag for each file:

• Format (.docx, .docm, .xlsx, .xlsm, .pptx, etc.)
• Contains macros or embedded objects
• Is template (.dotx/.xltx) or content
• Business owner and retention requirements

Simple UNIX commands give a fast baseline (run against exported shares):

find . -type f \( -iname "*.doc*" -o -iname "*.xls*" -o -iname "*.ppt*" \) -print | sed -n '1,200p'

For macro detection, tag files with macro-enabled extensions (.docm, .xlsm). For deeper inspection, use the file and unzip trick to check embedded vbaProject.bin.

Phase 3 — Choose target formats

Pick the right tool for the job:

• Text-first docs (preferred): Markdown (.md), AsciiDoc (.adoc) or reStructuredText — best for developer-facing docs, changelogs, READMEs, and specifications. Easier to diff, review and automate.
• Rich documents: ODF formats (.odt, .ods, .odp) for letters, legal forms or layout-sensitive files you still want WYSIWYG editing for in LibreOffice.
• Spreadsheets: If spreadsheets are calculation-heavy and use complex Excel formulas/macros, evaluate keeping them as XLSX with Git LFS or migrating logic to scripts (Python/pandas/Jupyter) and storing results as CSV/ODS.
• Presentations: Convert to .odp or use Markdown-driven slide tools (reveal.js, AsciiDoc + Reveal) for reproducible slide builds.

Phase 4 — Conversion tooling and rules

Automated conversion is the backbone of a reproducible migration. Key tools:

• LibreOffice headless (soffice) — reliable batch conversion: soffice --headless --convert-to odt file.docx
• Pandoc — excellent for DOCX <-> Markdown conversions and templating; in 2025–2026 Pandoc tooling gained better docx handling.
• unoconv / LibreOfficeKit — alternatives for programmatic conversions in containers.

Example bulk conversion script (POSIX):

#!/bin/sh
  mkdir -p converted/odt
  for f in $(find exported -iname '*.docx'); do
    soffice --headless --convert-to odt --outdir converted/odt "$f"
  done
  

Conversion caveats and how to mitigate:

• Macros: Can't be automatically ported. Identify macro owners and decide to (a) rewrite macros in Python for LibreOffice, (b) remove macros and replace with external scripts, or (c) retain XLSM/XLSX under Git LFS for a limited set of files.
• Spreadsheet formulas: Some Excel-only functions may not map to ODS. For critical calculation sheets, create an automated test-suite to validate outputs against known inputs.
• Track changes/comments: Track changes import between ecosystems can be lossy. Export review history as PDF before converting and reconcile comments in the new workflow.

Phase 5 — Templates, macros and governance

Centralize templates as versioned .ott (LibreOffice template) files in a Git repo. That repo becomes the single source of truth for corporate letterheads, release notes templates and SOPs.

• Create a templates/ repo with subfolders by team and add CI validation for template signatures and metadata.
• Define macro policy: only signed templates with approved macros run; maintain a registry of macro authors and code reviews for macro updates.

Store macros as repository code (Python or LibreOffice Basic) and include unit tests where feasible. For security, scan macros for risky API usages as part of CI.

Phase 6 — Git workflows for docs

Shift collaboration from co-editing in a live document to a PR-driven workflow. Key patterns:

• Doc-as-code: Author in Markdown/AsciiDoc where possible and store in Git with the same branching model as code.
• Review & CI: Use pull requests for review and require checks (lint, build, accessibility) before merge.
• Binary handling: For ODF files that must remain binary, use Git LFS, and require a preview generation step that converts ODF > PDF for review.
• Diffing: Convert ODF to text (for example, using pandoc or odt2txt) during CI so reviewers can see meaningful diffs in PRs.

Sample repository structure:

docs/
    guides/
    api/
  templates/
    letterhead.ott
  spreadsheets/
    release-calculations.ods (or xlsx with LFS)
  .github/workflows/doc-build.yml
  

Phase 7 — CI/CD integration and automation

CI turns LibreOffice + Git from a file store into a production-ready, auditable pipeline. Typical CI jobs:

• Validation: Lint Markdown/AsciiDoc, check ODF schema, scan for macro policy violations.
• Render: Convert Markdown or ODT to HTML/PDF for distribution and review artifacts.
• Diff generation: Produce text diffs for ODT changes so PRs show readable changes.
• Release packaging: On tag, build and sign templates, produce PDF/A archives for compliance.

Example GitHub Actions workflow (simplified):

name: Doc Build
on: [pull_request, push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup LibreOffice
        run: sudo apt-get update && sudo apt-get install -y libreoffice
      - name: Convert ODT to PDF for review
        run: |
          mkdir -p artifacts
          for f in $(find docs -iname '*.odt'); do
            soffice --headless --convert-to pdf --outdir artifacts "$f"
          done
      - name: Upload review artifacts
        uses: actions/upload-artifact@v4
        with:
          name: docs-pdfs
          path: artifacts/
  

For heavy conversion you can run LibreOffice in a Docker container or use a prebuilt image with LibreOfficeKit. Use artifact storage to attach PDFs to PRs for reviewers who don't run LibreOffice locally.

Pre-commit & repository policies

Use pre-commit or Git hooks to enforce repository rules before pushing:

• Prevent .docx/.pptx in protected branches unless tagged for an exception.
• Validate template metadata (version, owner) on template commits.
• Check for large binary files and redirect them to Git LFS.

Compatibility and risk matrix

Most text and layout survive conversion well, but expect differences. Here’s a practical risk matrix:

• Low risk: Simple DOCX > ODT documents, basic formatting, images.
• Medium risk: Complex layouts, styles mapping, footnotes and cross-references.
• High risk: VBA macros, Excel-only functions, embedded OLE objects, SmartArt.

For medium/high risk files, create a controlled manual conversion workflow: export, convert, manual QC, signer approval, and archival of original for audit. Keep records of conversion results in the repo.

Training, rollout and change management

Successful adoption depends on developer and writer ergonomics:

• Run hands-on workshops: conversion demos, template usage, and PR review flows.
• Create a cheat-sheet with migration commands, common gotchas and where to open tickets.
• Set a staged timeline: pilot team (2–4 weeks), larger rollout (2–3 months), full retirement of Microsoft 365 (6–12 months) for target teams.

Metrics to track progress

• % of docs in text-first formats
• Number of templates in Git with CI validation
• Average turnaround for doc PRs (baseline and target)
• Cost delta vs. Microsoft 365 subscriptions
• Number of macro-enabled legacy files remaining

Practical examples and snippets

Convert a DOCX to Markdown with Pandoc (useful for API docs or specs):

pandoc -f docx -t gfm -o spec.md spec.docx

Create a Git LFS rule for spreadsheets in .gitattributes:

*.xlsx filter=lfs diff=lfs merge=lfs -text
*.xlsm filter=lfs diff=lfs merge=lfs -text
*.ods filter=lfs diff=lfs merge=lfs -text

Generate a human-readable diff for an ODT in CI by converting it to plain text first:

soffice --headless --convert-to txt:Text myfile.odt --outdir /tmp
git diff --no-index /tmp/myfile.txt /tmp/myfile-new.txt

Real-world mini case study (illustrative)

Engineering Docs Team at AcmeSoft (hypothetical) had 1,200 DOCX files and 120 XLSM spreadsheets. After a 6-week pilot converting public docs to Markdown and moving design docs to ODT when layout mattered, PR-based reviews cut review turnarounds by 35% and eliminated 70% of Microsoft 365 seats for dev teams. Critical XLSM files were reimplemented in Python scripts, adding reproducible unit tests and pushing outputs to CSVs committed to Git.

Common migration pitfalls and remedies

• Pitfall: Users resist switching because they miss live co-authoring. Remedy: Offer Collabora or Nextcloud integration for browser-based LibreOffice editing for non-developers, while keeping the canonical source in Git.
• Pitfall: Lost comments and review history. Remedy: Archive review snapshots (PDF) and attach to the PR or release artifact for audit trails.
• Pitfall: Hidden macro dependencies break processes. Remedy: Macro inventory and conversion-first approach—either rewrite in scripts or permit read-only retention under strict governance (see security & governance guidance).

Actionable checklist — first 8 weeks

1. Run inventory and tag macro-enabled files.
2. Choose target formats, define template repo structure.
3. Build small conversion scripts and test on a representative sample.
4. Set up a docs repo with pre-commit hooks and Git LFS rules.
5. Implement CI job to convert ODT & Markdown to PDF for PR previews.
6. Run pilot with one docs team; collect metrics and fix breakage.
7. Deliver training and FAQ; onboard second team.
8. Plan final cutover and decommissioning of Microsoft assets for covered teams.

Tip: Treat this migration like a software project—version everything, add tests, and enforce policy through CI. That converts an administrative migration into a reproducible engineering effort.

Final considerations — governance, signatures and archives

For regulated teams, produce signed PDF/A archives at release time. Integrate signing into CI using GPG or enterprise signing services. Keep original Microsoft artifacts archived with a clear retention label only when legally required.

Takeaways (what to do next)

• Start with a small pilot converting a single documentation repo to Markdown and a set of templates to .ott.
• Automate conversions and previews in CI so reviewers never need to install LibreOffice unless they want to edit.
• Make templates, macros and policies auditable and versioned in Git.
• Track progress with clear metrics and iterate—don’t attempt a big-bang cutover unless forced by compliance.

Call to action

Ready to migrate your dev and docs teams off Microsoft 365? Clone our starter repo with conversion scripts, CI workflows and template examples, run the pilot, and share your results with the community. For a tailored migration assessment and a checklist you can run in your CI, contact opensources.live or download the migration kit linked on this page.

Related Reading

• How Smart File Workflows Meet Edge Data Platforms in 2026
• Urgent: Best Practices After a Document Capture Privacy Incident (2026 Guidance)
• Security & Reliability: Zero Trust and Access Governance for Documents
• Cloud Native Observability: Architectures for Hybrid Cloud and Edge in 2026
• What Vice Media’s C‑Suite Shakeup Means for Local Studios and Content Houses in Dhaka
• Editing for Empathy: Video Techniques to Tell Difficult Domino Stories (and Stay Monetizable)
• How to Build a Cozy Cinema Corner: Rugs + RGBIC Lamp + Bluetooth Speaker
• Why a Mac mini M4 Is the Best Budget Desktop for Beauty Content Creators
• How to Build an Internal App Catalog: Curating approved micro and no-code apps for business teams