Full migration of Groups/Projects/Repositories from gitlab to github including Issues, Milestones, Labels, PRs, Wiki etc.

[tickytacky]

🏷️ Discussion Type

Question

Body

Hi,

we have to migrate about 20 projects which reside in 5 different groups from gitlab to github. We have implemented a python script which does most of the work. Currently we struggle with the following issues:

• How can attachments, mainly images but also documents/emails, that are embedded in the body of gitlab issues/comments be migrated to github, as there seems to be no API in github for that? We have already tried to upload the attachments as assets to the specific repository and change the links within the body of the issues. This basically works, but in the correspoding github Issue the attachment (e.g. image) is not rendered as image. With the pure link to the file in the repo it would work, but we want to have all images to be rendered in the issue/comment body. And further more having hundreds of attachment files for issues in the repo is an unwanted overhead.

• In gitlab, Issues can be linked ("Linked items"), also across Groups (Organisations in github). In github there seems to be only a hierarchy linking with Parent/Subitems. But we need linking on a horizontal level like "this Issue is related to one or more other Issues", but they do not depend on each other. Does github has such a functionality and if yes how can these relations be migrated? Simply adding a link to the issue body is not an appropriate solution, as this would have to be done manually for each related issue. So this is not only a migration topic but also important for our future working with github.

• Is there really no way to manage Milestones on Organisation-Level?

Cheers,
Harry

[shubham055555]

This is a well-described migration scenario, and you’ve already covered a lot of the hard parts. Let me address each of your points:

1. Attachments in Issues / Comments

You’re correct that GitHub does not provide a direct API equivalent to GitLab’s attachment handling inside issue bodies.

A few practical approaches:

• Use GitHub issue uploads (recommended workaround):
  When files are uploaded via the GitHub UI, they are stored on GitHub’s CDN and rendered inline automatically.
  However, this is not directly exposed via a public API.

• Workaround via GitHubusercontent URLs:
  You can upload files to a temporary issue/comment (via automation or bot), capture the generated CDN URL (user-images.githubusercontent.com), and reuse that URL inside migrated issue bodies. These will render correctly.

• Avoid storing in repo:
  As you observed, storing attachments inside the repository leads to clutter and does not render inline unless using raw URLs.

So in practice, most large migrations use a two-step upload + replace strategy with CDN links.

---

2. Issue-to-Issue Relationships (Horizontal Linking)

GitHub does not have a direct equivalent to GitLab’s “Linked items” (non-hierarchical relationships).

Available options:

• Issue references (lightweight):
  Mentioning another issue (e.g., #123) creates a backlink automatically.

• Projects (Beta) / Project Items:
  You can group related issues within the same project and use custom fields to represent relationships.

• Automation approach:
  During migration, you can programmatically insert structured references (e.g., “Related: #123, #124”) in issue bodies.

There is currently no native “related issues” API with first-class relationship types like GitLab.

---

3. Milestones at Organization Level

You are correct — GitHub milestones are repository-scoped only.

Workarounds:

• Use GitHub Projects (recommended):
  Projects (especially Projects v2) can act as an organization-level planning layer across multiple repositories.

• Naming convention for milestones:
  Some teams standardize milestone names across repos, but they are still managed separately.

---

Summary

• Attachments: Use GitHub CDN upload workaround for inline rendering
• Issue relationships: Use references or Projects (no true equivalent to GitLab linked items)
• Milestones: No org-level support; use Projects instead

---

For large-scale migrations like yours, combining automation scripts + GitHub Projects + CDN-based attachment handling is currently the most practical approach.

Hope this helps streamline your migration.

[hesxo]

You’re running into a few GitHub model differences here.

For attachments: GitHub’s issue APIs cover issues, comments, labels, milestones, dependencies, and issue fields, but there is no documented issue/comment attachment upload endpoint in the REST issues API. File attachment is documented as a web UI flow: drag/drop or attach in the comment box, which uploads the file and inserts an anonymized URL into the text. 

So for migration, the practical options are:
• host the files somewhere stable and rewrite the Markdown to point to those direct URLs
• or store them in the repo and rewrite image links to the raw/direct file URL, not the normal repo page URL

If you link to the normal repository file page, GitHub won’t render it inline as an image in the issue body. You need normal Markdown image syntax with a direct image URL, and if you use repo files, a permalinked/raw target is the safer choice. 

For issue-to-issue relationships: GitHub does have structured relationships now, but they are mainly:
• parent / sub-issues
• dependencies (“blocked by” / “blocking”)

Sub-issues are hierarchical, so they do not match your “related but not dependent” case. Dependencies are closer, but still imply dependency semantics rather than a neutral “related to” link. I’m not aware of a first-class horizontal “related issues” relationship equivalent to GitLab’s linked items. The closest native workaround is usually a custom organization issue field plus Projects views, or plain cross-links in the body/comments. 

For milestones: GitHub milestones are still repository-scoped, not organization-scoped. The docs describe milestones as tracking issues and PRs in a repository. If you need org-level planning, GitHub’s newer org-level issue fields / Projects are the better fit.