## Problem to solve An organization importing their work in progress from GitHub into GitLab expects all of the data concepts that exist in GitLab to be automatically migrated from GitHub. However, some GitHub concepts, such as Organizations, Teams, Releases, and Gists are currently not included in the import. Leaving this data behind could be a deal-breaker for a large organization that relies on that concept where a manual workaround for the import would be cost-prohibitive due to their size. ## Proposed solution In order to solve this problem and meet user expectations, we need to complete the GitHub Importer by implementing the import of all relevant GitHub concepts that have a matching feature in GitLab: 1. Import GitHub events - https://gitlab.com/groups/gitlab-org/-/epics/7655 &7673 * [Configurable list of things 'to be imported' that can be adjusted by the user](https://gitlab.com/gitlab-org/gitlab/-/issues/370734) (closed) 1. Import GitHub branches - https://gitlab.com/gitlab-org/gitlab/-/issues/22650 https://gitlab.com/groups/gitlab-org/-/epics/8585 1. Import GitHub releases - https://gitlab.com/gitlab-org/gitlab/-/issues/15620 1. Import GitHub dashboards into issue boards - https://gitlab.com/gitlab-org/gitlab/-/issues/25569 1. Import GitHub Gists as snippets - https://gitlab.com/groups/gitlab-org/-/epics/8536 1. Fix high priority issues with the current import - https://gitlab.com/gitlab-org/gitlab/-/issues/18052 https://gitlab.com/gitlab-org/gitlab/-/issues/23100 https://gitlab.com/gitlab-org/gitlab/-/issues/354848 1. Import GitHub Organizations into GitLab Groups - https://gitlab.com/groups/gitlab-org/-/epics/7307 <!-- Full list: 1. Fix high priority issues with the current import - https://gitlab.com/gitlab-org/gitlab/-/issues/18052 https://gitlab.com/gitlab-org/gitlab/-/issues/23100 1. Import GitHub Organizations into GitLab Groups - https://gitlab.com/groups/gitlab-org/-/epics/7307 1. Import GitHub actions 1. Import GitHub events - https://gitlab.com/gitlab-org/gitlab/-/issues/15178 1. Import GitHub repo stars 1. Import GitHub Pages sites 1. Import GitHub Gists as snippets - https://gitlab.com/gitlab-org/gitlab/-/issues/22674 1. Import GitHub releases - https://gitlab.com/gitlab-org/gitlab/-/issues/15620 1. Import GitHub branches - https://gitlab.com/gitlab-org/gitlab/-/issues/22650 1. Import GitHub push rules 1. Import GitHub webhooks 1. Import GitHub deploy keys 1. Import GitHub dashboards into issue boards - https://gitlab.com/gitlab-org/gitlab/-/issues/25569 1. Import GitHub teams into subgroups 1. Import GitHub collaborators as group members --> ## Further details ### Concept mapping GitHub to GitLab This is an overview of the GitHub concepts and how they map to GitLab concepts. This table is informational and not exhaustive. | GitHub concept | GitLab concept | Exists in GitLab | Current import | Future import | |------------------|------------------|-------------------|-------------------|-----------------| | Organization | Group | ✅ | ❌ | ✅ | | Team | Subgroup ? | ❗ | ❌ | ❓ | | Collaborator | Member | ✅ | ✅ | ✅ | | Repository | Project | ✅ | ✅ | ✅ | | Pull request | Merge request | ✅ | ✅ | ✅ | | Issue | Issue | ✅ | ✅ | ✅ | | Comment | Comment | ✅ | ✅ | ✅ | | Author | Author | ✅ | ✅ | ✅ | | Label | Label | ✅ | ✅ | ✅ | | Action | Action | ✅ | ❌ | ✅ | | Event | Event | ✅ | ✅ issue & PR events | ✅ | | Dashboard | Issue board | ❗ | ❌ | ✅ | | Wiki | Wiki | ✅ | ✅ | ✅ | | Repo star | Project star | ✅ | ❌ | ❓ | | Follower | | ❌ | ❌ | ❌ | | Milestone | Milestone | ✅ | ✅ | ✅ | | GIST | Snippet | ❗ | ✅ | ✅ | | Pages | Pages | ✅ | ❌ | ✅ | | Release | Release | ✅ | ❌ | ✅ | | Package | Package | ✅ | ❌ | ❌ | | Branch | Branch | ✅ | ❗ | ✅ | | Push rules | Push rules | ✅ | ❌ | ✅ | | Security | | ❌ | ❌ | ❌ | | Notification | Notification | ✅ | ❌ | ❓ | | Integrations | Integrations | ✅ | ❌ | ❌ | | Services (depr.) | | ❌ | ❌ | ❌ | | Webhooks | Webhooks | ✅ | ❌ | ❓ | | Deploy keys | Deploy keys | ✅ | ❌ | ❓ | | Secrets | Variables ? | ❗ | ❌ | ❓ | | User | User | ✅ | ❌ | ❌ | ##### Legend: Compatibility * ✅ - Full compatibility. * ❗ - Partial compatibility / Hacky workaround. * ❌ - Insufficient compatibility. We would need to create a similar concept within GitLab first in order to have a meaningful mapping between the two services. ### Out of Scope The following features are not being considered for implementation at this time. They may be considered in the future. 1. Import GitHub secrets into variables 1. Import GitHub users 1. Import GitHub notifications 1. Import GitHub packages 1. Import GitHub user and profile - https://gitlab.com/gitlab-org/gitlab/-/issues/22560 ## Questions an Answers * [ ] Will all the above objects be available in GitHub API? * [x] GitHub API rate limits? * Already being respected - https://gitlab.com/gitlab-org/gitlab/-/issues/213314#note_467648457 * [x] How do we expect the Stars to work? * Repository Stars should be mapped to Project Stars * [ ] What does the customer data look like? What objects do they use? * [x] Are there security concerns around automatic user creation? Why we never did it? * Automatic user creation no longer considered in scope. * [x] Idea: create a pre-import check/report to inform about missing users, etc... * [Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/294122) created * [x] UX for self-service migrations of 1000+ orgs... * Individual moves * Admins should be able to see the overall progress, what's left behind * [Epic](https://gitlab.com/groups/gitlab-org/-/epics/5042) created ### ToDo * [x] Build a matrix of what we already migrate, what concepts already exist in GL, but are not currently migrated, which concepts do no exist in GL, and which objects are currently not exposed in GitHub API. ## Links * [Current GitHub Importer Docs](https://docs.gitlab.com/ee/user/project/import/github.html)