Change your username in GitLab settings

To change your GitLab username, go to your account settings, find the username field, enter the new name, and save. The process takes about two minutes and you can do it from any device with internet access. GitLab will update your profile when ready, though some parts of the system (like project URLs) may take a few minutes to catch up.

Your username is different from your display name. The username is what appears in your profile URL — gitlab.com/yourname — and in mentions like @yourname. The display name is just what shows on your profile card. This guide covers changing the username itself.

Key Takeaways

  • Log into GitLab, click your avatar in the top right, select Preferences, then click Edit Profile to find the username field.
  • Your new username must be lowercase, between 1 and 255 characters, and can only contain letters, numbers, hyphens, and underscores.
  • Changing your username updates your profile URL and mentions, but old links to your projects may break until GitLab's system catches up.
  • If you are part of a group or organization, changing your username does not affect your membership or permissions.
  • You can change your username as many times as you want, but GitLab may rate-limit very frequent changes.

Step-by-step: finding and editing your username

Start by signing into GitLab. In the top right corner, you will see your avatar (a small circle with your initials or profile picture). Click it to open a dropdown menu.

From that menu, click Preferences. This opens your account settings page. On the left side, you will see several tabs. Click Edit Profile — it is usually the first option. Scroll down until you see the Username field. It will show your current username in a text box.

Click inside the username field and clear the old name. Type your new username. Remember that GitLab usernames are case-insensitive, so "JohnDoe" and "johndoe" are treated as the same username. After you type the new name, scroll to the bottom of the page and click the Update Profile Settings button (or similar — the exact button text varies by GitLab version).

Rules for valid GitLab usernames

GitLab enforces specific rules about what characters and lengths are allowed. Your username must be between 1 and 255 characters long. It can contain letters (a–z), numbers (0–9), hyphens (-), and underscores (_). Spaces, periods, and special characters like @ or # are not allowed.

The username must start with a letter or number — it cannot start with a hyphen or underscore. GitLab will reject the change if you try to use a name that breaks these rules, and it will show an error message telling you what went wrong. If you see an error, check that you have not used any spaces or special characters.

Your new username also cannot already be taken by another user or reserved by GitLab itself. If you try to use a name that is already in use, GitLab will tell you the username is unavailable. Try a variation — adding a number or underscore often solves this.

What happens to your old profile links and mentions

When you change your username, your profile URL changes when ready. If your old URL was gitlab.com/oldname, it becomes gitlab.com/newname. Any bookmarks or links to your old profile URL will no longer work. If you have shared your profile link with others, you will need to send them the new URL.

Mentions of you in comments, issues, and merge requests will still work. If someone mentioned @oldname before you changed it, GitLab keeps a record of that mention and it will still point to your account. However, new mentions must use your new username — @oldname will no longer autocomplete or notify you.

Project URLs that include your username (like gitlab.com/yourname/project-name) will also change. If you have cloned a repository using the old URL, your local copy will still work, but you may need to update the remote URL in your Git configuration to push and pull changes. You can do this by running git remote set-url origin [new-url] in your local repository.

Changing your username if you are in a group or organization

If you are a member of a GitLab group or organization, changing your username does not affect your membership or your permissions. You will still have the same access level (Developer, Maintainer, Owner, etc.) in all groups you belong to. The group will straightforward show your new username in the member list.

If you are the owner of a group, changing your username does not transfer ownership. You remain the owner under your new username. However, if your group has a custom URL that includes your old username, that URL will no longer work — you may need to update it in the group settings if you want to keep the same URL.

Undoing a username change

GitLab does not have an "undo" button for username changes, but you can change it back by following the same steps. Go to your Preferences, click Edit Profile, change the username field back to your old name, and save. As long as no one else has claimed your old username in the meantime, you can reclaim it.

If someone else has taken your old username, you will need to choose a different one. This is rare, but it can happen if you change your username and then wait a long time before changing it back. For this reason, if you are unsure about a new username, test it for a day or two before deciding to keep it permanently.

Troubleshooting common problems

If you see an error message saying "Username has already been taken," the name you chose is in use. Try adding a number or underscore to make it unique. If the error says "Username is invalid," you have used a character that GitLab does not allow — check that you have only letters, numbers, hyphens, and underscores.

If you changed your username but old links still show the old name, wait a few minutes. GitLab's cache system takes time to update across all servers. Refresh the page or clear your browser cache (Ctrl+Shift+Delete on Windows, Cmd+Shift+Delete on Mac) to see the new username right away.

If you cannot find the username field in your settings, you may not have permission to change it. Some GitLab instances (especially those run by companies or schools) restrict username changes to administrators only. Contact your GitLab administrator if you do not see the username field in your Edit Profile page.

Frequently Asked Questions

Can I change my username if I have active projects or repositories?

Yes, you can change your username at any time, even if you have projects. Your projects will move to the new username URL. Anyone who has cloned your repositories will need to update their remote URL, but the repositories themselves are not affected. You can update a local clone by running git remote set-url origin [new-url] in the repository folder.

Will changing my username affect my SSH keys or access tokens?

No. Your SSH keys and personal access tokens are tied to your account, not your username. They will continue to work after you change your username. You do not need to regenerate them or update any configuration.

How often can I change my username?

GitLab allows you to change your username as many times as you want. However, if you change it very frequently (multiple times per day), GitLab may temporarily rate-limit the changes to prevent abuse. In practice, most users never hit this limit.

What happens to my old username after I change it?

Your old username becomes available for other users to claim after a short waiting period (usually a few days to a week, depending on your GitLab instance). If you think you might want to use it again, change back to it before someone else does.

Can I use special characters like dots or hyphens in my username?

Hyphens and underscores are allowed. Dots, spaces, and other special characters are not. If you want to separate words in your username, use a hyphen (like john-doe) or underscore (like john_doe) instead.