Change your GitLab username in Settings

To change your GitLab username, go to your account settings and find the username field under the Account section. Click Edit next to your current username, type the new one you want, and click Update username. GitLab will check whether the new name is available before you confirm the change.

The change takes effect when ready. Your old username becomes available for other users to claim after a short delay, usually within a few hours. Any projects, groups, or profile links using your old username will redirect to your new one for a limited time, but you should update any bookmarks or shared links yourself to avoid confusion.

You can change your username as often as you want, but GitLab may rate-limit very frequent changes. If you change your username multiple times in a short period, you may see a message asking you to wait before making another change.

Key Takeaways

  • Navigate to your account settings, find the Account section, and click Edit next to your username to change it.
  • Your new username takes effect right away, and old links redirect temporarily but should be updated by you.
  • The username you choose must not already be in use and must follow GitLab's naming rules (lowercase letters, numbers, hyphens, and underscores only).
  • Changing your username does not affect your email address, password, or any of your projects or group memberships.

Username rules and what you cannot use

GitLab usernames must be between 1 and 255 characters and can only contain lowercase letters, numbers, hyphens, and underscores. Uppercase letters are not allowed — GitLab converts them to lowercase automatically. Spaces and special characters like periods, slashes, or @ symbols are not permitted.

You cannot use a username that is already taken by another user or reserved by GitLab itself. Reserved names include system accounts like root, admin, and api. If you try to use a reserved name or one that belongs to someone else, GitLab will show an error and ask you to choose a different one.

What happens to your old username

When you change your username, GitLab keeps your old one unavailable for a grace period — usually 30 days. During this time, anyone who visits your old profile URL will be redirected to your new one. After the grace period ends, your old username becomes available for other users to register.

Your project URLs, group URLs, and any links that included your old username will still work during the grace period because of the redirect. However, if someone else claims your old username after the grace period, those redirects will stop working. For this reason, you should update any important links — such as those in your resume, portfolio, or documentation — to use your new username right away.

How your projects and groups are affected

Changing your username does not move, delete, or rename any of your projects or groups. They stay exactly where they are, with the same names and the same content. However, the URLs that point to those projects will change to reflect your new username.

For example, if your old username was alex-smith and your project was called my-app, the old URL would be gitlab.com/alex-smith/my-app. After you change your username to asmith, the new URL becomes gitlab.com/asmith/my-app. The project itself is unchanged — only the path in the URL is different.

If you have shared your project URL with others or linked to it from external sites, those old URLs will redirect to the new ones during the grace period. After that, the old links will break. Update any documentation, README files, or external links that point to your projects to use the new username.

Changing your username on a self-hosted GitLab instance

If you use GitLab on your own server (a self-hosted instance) rather than GitLab.com, the process is the same: go to your account settings, find the Account section, and edit your username. The same rules explore — lowercase letters, numbers, hyphens, and underscores only.

The grace period and redirect behavior depend on how your instance is configured. Some self-hosted instances may have different settings for how long old usernames stay reserved or whether redirects are enabled. If you are unsure about your instance's settings, contact your GitLab administrator.

Troubleshooting username change problems

If you see an error saying your new username is not available, it means either someone else is already using it or it is a reserved name. Try a different username. If you believe the username should be available, wait a few minutes and try again — sometimes there is a slight delay in the system updating.

If you cannot find the username field in your settings, make sure you are logged in and viewing your own account settings, not someone else's profile. Go to the menu in the top right corner of GitLab, click your avatar, and select Edit profile. Then click Account in the left sidebar to find the username field.

If you changed your username but your old links are not redirecting, the grace period may have ended. Check whether someone else has claimed your old username. If they have, the old links will no longer work, and you will need to update them manually.

Frequently Asked Questions

Can I change my username back to what it was before?

Yes, as long as no one else has claimed it. If your grace period has not ended, your old username is still reserved and you can change back to it. If the grace period has ended and someone else registered the old name, you cannot use it again unless that person gives it up.

Does changing my username affect my email address or password?

No. Your email address and password remain the same. You log in with your email address and password, not your username, so changing your username does not affect how you sign in to GitLab.

What happens to my SSH keys and personal access tokens when I change my username?

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

If I change my username, will my followers or people watching my projects be notified?

No. GitLab does not send notifications when you change your username. People who follow you or watch your projects will see your new username the next time they visit your profile or project, but they will not receive a notification about the change.

Can I use a username that contains uppercase letters?

No. GitLab only allows lowercase letters in usernames. If you type uppercase letters, GitLab will convert them to lowercase automatically. For example, AlexSmith becomes alexsmith.