How to change your username in GitLab.com without breaking anything
How to change your username at GitLab.com
- Starting point: let's say your username is smt like
old-maryand you want it to be just
- Note: each GitLab account is tracked by an userID, which is a number stored in a database. If we change the username, the userID does not change. And all the permissions, issues, MRs and relevant stuff within GitLab is related with your userID, not with your username.
- Note: if you are not a GitLab Team member, the same process applies; except your e-mail (STEP 2), which will be different (will not be @gitlab.com email), so you can replace it with your own email account.
STEP 1: request your new username
- Access the username you want to request via
- Check it's activity, projects, to see if he/she is an inactive - according to the handbook
- Send your request to support at gitlab dot com, explaining the reasons why you need that username.
- There's no guarantee that the username will be available for you. Please check the handbook guidelines for dormant usernames
STEP 2: create a new account with your new username
- If support replies to you telling that the username is free to use, create a new GitLab.com account with it. Use a personal email to register your new account and choose one that has not been used with your old GitLab account.
- Navigate to your profile settings > emails, and add a new email !trick! If your email at GitLab is
firstname.lastname@example.org, add the new email as
email@example.com: this is a Gmail trick! All your emails sent to this alias will end up in your GitLab email account
- Navigate to https://gitlab.com/profile/notifications and choose the notifications email:
- Open your old account in one browser and the new one in another browser (e.g., Chrome and Firefox, or Chrome and Safari) - log in to both accounts at the same time
STEP 3: let's have some fun (kidding, this is critical!)
- Navigate to https://gitlab.com/profile/account in both your accounts.
- Look for your username. This operation has to be done quickly, otherwise you as risking to loose your awesome new username to someone else quicker than you. We need to swap the usernames between both accounts, so you'll keep all your history, your privileges, issues and MRs assigned to you, etc.
- If you work with 2 monitors, open each browser on one monitor. If you don't, open them in parallel, so that you can keep an eye on both at the same time.
- Rename your new username
maryto smt like
mary-1and DO NOT click update username yet. Rename your old username
old-maryto your new username
maryand don't update that either. Just leave them typed into the boxes.
- Make sure you did the previous step right :D
CRITICAL! Update the first one (
mary-1). Immediately, click
updateon the other one (
- Immediately, rename the
mary-1to your old one
old-maryand click "update username" again.
STEP 4: move your projects (or not)
- Now, if you have any personal projects, you might want to import them to your new account (the one that has your old username now). To do that, in your new account (the one with the old username), click "create a new project", give it the very same name as the original one, click "git - add repo by url", and paste the
https://url of your project there. To make things easier, make sure all the projects you want to import are set to
publicview. You can make them private afterwards.
- If you have GitLab Pages projects with the default GitLab.io url, you will need to import them to you new account, then make a change to trigger a build and redeploy your site. This won't affect Pages projects that use custom domains, as they all point to the same Pages server. They will be affected if you're using a CNAME with a subdomain instead of an A record. Your groups won't be affected either, as they operate under their own namespace. Add both users as members of your groups and nothing changes.
Pretty exciting thing to do! :)
I wonder where should we add this to the handbook. @ashleys what do you think? Is the process clear? Which handbook?
cc/ @stanhu :)