Onboarding story: importing projects from GitLab.com to self-hosted GitLab
Not that smooth, as you might expect
If you’re tired from GitLab.com slowness, or no longer trust Yorick to keep an eye on your data, it makes total sense to set up your own instance of GitLab. I decided to do that, and below is the report about my onboarding process.
Installation and registration
GitLab CE installation with omnibus was straightforward as usual. But the rest of the experience was not so smooth.
It asks you to set up a new password, then you had to register a new user. It doesn’t make a lot of sense actually. Also, GitLab assumes I should know login or email of admin user, but I didn’t.
Trying to import projects from GitLab.com
I decided to import my project from GitLab.com, but it asked to configure OAuth integration first:
The beginning of the documentation page:
Screenshot looks outdated:
The final line #14 of the OAuth configuration manual was “Restart GitLab for the changes to take effect”. But there was no mention on how to do that.
So I had to google how to restart GitLab instance. Found this:
After restarting my GitLab started to report error 502:
That was kind of scary. First thought was that I broke the configuration file or something. I decided to rollback my changes in configuration and waited for a couple of minutes it returned to working state.
Then I realized that after every restart you need to wait for a while for GitLab to actually start. This is a bit confusing and annoying.
Anyhow, GitLab works, I put my config back, and it looks like I can finally import our project from GitLab.com. No, I can’t :( The same message:
It is kind of confusing again. I started to think that I might need to log in to my instance using GitLab.com first to be able to import projects from there.
I googled and found another documentation page:
https://docs.gitlab.com/ee/workflow/importing/README.html
The right link for import from GitLab.com to self-hosted GitLab:
https://docs.gitlab.com/ee/workflow/importing/import_projects_from_gitlab_com.html
Another outdated screenshot met me there:
And the small link leads to the same page: https://docs.gitlab.com/ce/integration/gitlab.html :(
Ok, trying to find a clue in the config itself:
Maybe I should specify more options to make it work. Here’s my config now:
Forgot how to restart again. Googled. Found: “sudo gitlab-ctl restart”
No luck. The same “To enable importing projects from GitLab.com, ask your GitLab administrator to configure OAuth integration”.
Another guess. Maybe I’ll be able to do something about it if I log in as admin to my GitLab. But I didn’t know admin’s email.
Obtaining GitLab admin email
The only way to find admin’s email, which came into my mind was to do it manually in rails console. At this point, I’ve already forgotten admin’s password. So this link I found was pretty useful:
Mistake realization
At this point, I realized my mistake. I should have been added an app on GitLab.com, not in my own instance. Actually, it makes sense, and the documentation explicitly says to do so, but it is very easy to do this mistake since I had two GitLabs, and was trying to configure self-hosted one.
Ok, I’ve created an app on GitLab.com, changed my config and restarted. Without success. Despair :(
Reconfiguring
A day after support said that I should have been reconfigured my GitLab. But documentation has never mentioned that!
Ok, googling. Found: “sudo gitlab-ctl reconfigure”
Reconfiguring. Restarting. And it worked! Hooray!
Importing projects
Some projects were imported fine, some have failed:
Not sure what to do with failed, why they failed and how to fix that :\
Fighting with projects limit
Oh, this is funny! GitLab actually lets me import twelve projects. Then it finally noticed that I am allowed to have only ten:
Googled how to increase the limit. Found this on Stackoverflow. Looks confusing. It can’t be true that I have to change the source code to adjust a number of project limit.
Doesn’t seems to be in the config.rb either.
Probably I should log in as administrator and look for some kind of settings.
Ok, found how to make myself an admin. Found projects limit as well! Hooray!!! Changed the limit to zero, assuming it means “No limit”.
Returned back and tried to import other projects. That’s confusing. There was no “New project” button on /dashboard/projects page
Yup, it is just disappeared.
Maybe restarting GitLab could help? Nope, didn’t help :(
Ok, typed manually /projects/new in URL and it seem to work. Trying to import the rest of the projects.
Oh, no. Not again!! WTF! I already set the limit to zero. And I set myself as administrator. And I still can’t add a project :\
Ok, another guess: maybe setting projects limit to zero was a bad idea. I set it to 20000, and yay, “New project” button appeared.
Importing projects
It is not very convenient to have all the projects mixed in the same list. I’d like to be able to go through the list of personal projects only. At least first.
Also, they are not even sorted by type, so I had to scroll up and down to find my personal projects.
Failed import
Ha, interesting. It looks like the project with “failed” importing state have been actually imported. The project was created at least. Maybe something is missing… Oh right, it has no files at all. Deleted the project. Tried to re-import. Failed again :(
Looks like I had to add it manually later.
The sad thing is that GitLab gives no hints about what went wrong during the import. There’s also no indication in the half-imported project that there were problems during the import :(
If you will not pay enough attention to import status, you can conclude that project was imported successfully, delete the source on GitLab.com and as a result, loose your issues, milestones, and labels.
Ok, let’s do some housekeeping instead.
Housekeeping
Created some groups & transferred some top-level projects there. Worked well. There was only one inconsistency: when I forgot to change transfer destination and clicked “Import”, UI stopped to work correctly, so I had to refresh the page.
Summary
I have to say that it was not a very pleasant Admin Experience. GitLab could make the whole process much easier.
- Documentation didn’t mention crucial steps, like reconfiguring
- I had googled a lot. I counted 6 times.
- Documentation has outdated screenshots
- Importing errors are not explained, and you might end up having projects in broken state
In general, it looks like GitLab assumes that you are old friends, and you already know a lot about it.
So, GitLab hasn’t met my expectations. I was hoping to accomplish everything in one hour or so, but I was stuck a couple of times and had to wait for support to answer my question once, so it took a day to get it done. I know that I am not a very patient and thorough person, so I was trying to cut some corners by making guesses. Average administrator probably doesn’t look like me.
The trick is this is what User Experience means — you don’t need to follow long instructions to get everything done, you just follow your intuition, and it works as you expect. It is not the case in this part of GitLab yet.
Of course, I did very stupid mistake while creating an app for OAuth integration, but:
- It is easy to do a mistake when you have to follow 14-steps process
- Documentation doesn’t explain why is that even needed and what does it mean.
I bet the whole 14-steps process of OAuth integration setup could be simplified a lot. For example, when you import projects from GitHub to your instance, configuration takes only two steps: generate a token on GitHub, and copy & paste it to your GitLab. That’s it.
Come on, GitLab, you can do it much better, I know.
