Move the gitlab-docs project under the gitlab-org group
I don't remember why this project wasn't initiated under the gitlab-org
group, but I think it's time we discussed about transferring it.
Pros:
- Unified workflow: all boards under the
gitlab-org
roof, can create epics with issues related to both CE/EE and the gitlab-docs project
Cons:
- ?
Considerations/Implications
-
Registry - Are the Registry images migrated along with the project transfer? - No https://gitlab.com/gitlab-org/gitlab-ce/issues/33301, we need to delete the tags and then recreate them in the new transferred project.
-
Pages - How about Pages? Will they continue to work? - Yes, BUT the DNS records will need to be changed if we're using CNAME.
-
Labels - If we go with this we'd need to see where this is referenced and replace the URLs, and also find out if there will be any issues with the existing group labels that are under gitlab-com
. -
Milestones - What happens with the milestones? Will the project inherit the milestones of gitlab-org
?-
No - The issue references the old milestone URL https://gitlab.com/gl-docsteam-new/gitlab-docs/issues/1. Not sure what happens if the old group milestone is deleted.
- We can still search/filter the project referencing the milestone
- We can still search/filter the group referencing the milestone, since the new group also has the same milestone and the filter works on the milestone title (
milestone_title=11.7
) - The old group milestone (in)correctly shows there are issues https://gitlab.com/groups/gl-docsteam/-/milestones/1
- The issues/MRs don't show on the new group milestone https://gitlab.com/groups/gl-docsteam-new/-/milestones/1
- The issues/MRs cannot be filtered by that milestone on the new group's issue boards
-
No - The issue references the old milestone URL https://gitlab.com/gl-docsteam-new/gitlab-docs/issues/1. Not sure what happens if the old group milestone is deleted.
-
Epics - We have some epics at the gitlab-com group level https://gitlab.com/groups/gitlab-com/-/epics?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Documentation. What would happen if we moved the project? It's fine if we need to manually log which issues were part of which epic and re-create the epics; we'd just need to know that, and if we’re supposed to delete the old epics manually before the move, to prevent breaking anything. (I know we do not support moving epics to another group.) - Epics are not transferred, but they still retain the issues even though they are now in a new group. We'll have to manually re-create them in the new group.
Impact
- During the transfer, we get no new deployments (hourly schedules)
- Review apps will not work until all Docker images are uploaded and the group name is changed in the script that deploys review apps in CE/EE/Runner projects.
Testing
-
Create test project forked from gitlab-docs
https://gitlab.com/gl-docsteam/gitlab-docs-
Make sure all version branches build correctly -
Make sure all pipelines build correctly (create: single Docker images, archive Docker image, latest Docker image)
-
-
Create new group to migrate to https://gitlab.com/groups/gl-docsteam-new
- Old group - https://gitlab.com/groups/gl-docsteam/
- New group - https://gitlab.com/groups/gl-docsteam-new
-
Create same milestone name in new and old group -
Create group labels in both groups. -
One label with same name for both groups -
One label only in old group
-
-
Create an epic in the old group and attach an issue to it https://gitlab.com/groups/gl-docsteam/-/epics/1 -
Remove all Registry images https://gitlab.com/gl-docsteam/gitlab-docs/container_registry -
Transfer project https://gitlab.com/groups/gl-docsteam-new -
Check that Pages still work (they worked after changing the DNS record) -
Change all paths for ALL branches: find ./ -type f -exec sed -i 's/gl-docsteam\/gitlab-docs/gl-docsteam-new\/gitlab-docs/' {} \;
-
Rebuild all registry images -
Check that Pages still work -
Check the builds still work (master, scheduled pipelines, single/archive/latest Docker images -
Check Registry migration https://gitlab.com/gl-docsteam/gitlab-docs/container_registry -
Check that Pages still work after rebuilding the site http://docs2.axilleas.me -
Test issue redirection https://gitlab.com/gl-docsteam/gitlab-docs/issues/1 -
Check milestone migration -
Check label migration -
Check epic migration
You can see all my changes in https://gitlab.com/gl-docsteam/gitlab-docs/compare/cc8d66a146ba020e5268d77d38f8bdc809cfb884...master. I used a test site under my personal domain: http://docs2.axilleas.me (no https) using the Registry images uploaded in the forked project.
Before migration
-
Migrate to group milestones (there's only %10.0) https://gitlab.com/gitlab-com/gitlab-docs/milestones?sort=due_date_desc&state=all -
Make .gitlab-ci.yml
project-agnostic by providingCI_REGISTRY_IMAGE
instead of hardcoded paths. We can do this right away as it doesn't affect the existing project. -
Have an MR ready to be merged (but not merge!) as soon as the transfer is done for the following projects: -
gitlab-ce - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30620 -
gitlab-ee- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30620 -
omnibus-gitlab - No changes -
gitlab-runner - No changes -
gitlab-docs - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/486
Do this by replacing the occurrences of
gitlab-com/gitlab-docs
togitlab-org/gitlab-docs
:find ./ -type f -exec sed -i 's/gitlab-com\/gitlab-docs/gitlab-org\/gitlab-docs/' {} \;
-
-
Get a production engineer on-call for the next 30min to change the DNS record and solve anything else -
Remove all Registry images -
Disable the scheduled pipeline -
Transfer project
Immediately after migration
-
Change the DNS CNAME to point to the new group https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7235Not needed, we're using an A record -
Merge the gitlab-docs MR of the name change and cancel the pipeline as it will fail since there are no Registry images at this point !489 (merged) - Rebuild all the helper Registry images:
-
Run a manual job of image:bootstrap
. This will buildregistry.gitlab.com/gitlab-org/gitlab-docs:bootstrap
. Wait to upload the image. -
Run a manual job of image:builder-onbuild
. This will buildregistry.gitlab.com/gitlab-org/gitlab-docs:builder-onbuild
. -
Run a manual job of image:nginx-onbuild
. This will buildregistry.gitlab.com/gitlab-org/gitlab-docs:nginx-onbuild
.
-
- Rebuild all the versions Registry images:
-
The versions will be built by running a pipeline of the related branches/versions. This will be done by pushing to all respective branches: #!/bin/sh array=( 10.3 10.4 10.5 10.6 10.7 10.8 11.0 11.1 11.2 11.3 11.4 11.5 11.6 11.7 11.8 11.9 11.10 11.11 12.0 ) for REF in "${array[@]}" do git checkout $REF # Make sure we're on the right branch [ "$(git rev-parse --abbrev-ref HEAD)" == "$REF" ] || exit 1 find ./ -type f -exec sed -i 's/gitlab-com\/gitlab-docs/gitlab-org\/gitlab-docs/' {} \; git status echo echo "=> The above files have changed. Are you sure you want to commit and push? [N/y]" read answer [ "$answer" == "y" ] || (git checkout . ; exit 1) git add . git commit -m "Change project group to 'gitlab-org'" git push origin $REF done
-
Enable the scheduled pipeline and run it. This will build: registry.gitlab.com/gitlab-org/gitlab-docs:archives registry.gitlab.com/gitlab-org/gitlab-docs:latest
-
-
Merge the MRs of the name change for the following projects: - Although GitLab automatically supports redirects, let's find and replace all occurrences of
gitlab-com/gitlab-docs
. Create MRs for other projects:-
Handbook gitlab-com/www-gitlab-com!25871 (merged) -
Other GitLab projects?
-
-
Update our boards?
Checks
-
Check that Pages still work -
Check the builds still work (master, scheduled pipelines, single/archive/latest Docker images -
Check Registry migration https://gitlab.com/gitlab-org/gitlab-docs/container_registry -
Check that Pages still work after rebuilding the site https://docs.gitlab.com -
Test issue redirection https://gitlab.com/gitlab-com/gitlab-docs/issues/310 -
Check milestone migration -
Check label migration -
Check epic migration
Lastly:
-
Announce in team call -
How much of this process is documented? Make sure we update our docs with our findings.