Set your username for Bitbucket Cloud actions

Your commits happen on your local system and you push them to Bitbucket Cloud. Bitbucket uses the commit data to determine which account name to attach to the push in Bitbucket. To ensure your actions in Bitbucket appear with the correct user, you must configure your local DVCS correctly.

To map your username to a commit, push, and other activities, Bitbucket Cloud requires that the email address you commit with matches a validated email address on an account. On your local system, where you commit, both Git and Mercurial allow you to configure a global username/email and a repository specific username/email. If you do not specify a repository specific username/email values, both systems use the global default. So, for example, if your Bitbucket account has a validated email address of, you need to make sure your repository configuration is set for that username. Also, make sure you have set your global username/email address configuration to a validated email address.

If the global default is not configured or if you have not validated your email address, the committer appears as unknown for your Bitbucket activities. Also, if you have multiple Bitbucket accounts, you may mistakenly commit your code under an email address that maps to an account name you did not intend. To have the existing commits on a repository map to a different account, you can use  Username aliases for the repository in question. Aliases are per-repository. To set up an alias for a repository, you must have admin rights on it.

This page contains the following topics:

Git username/email configuration

Configuring Git works the same across GitBash (Windows) , Mac OS X, and Linux-based systems. To set your global username/email configuration, do the following:

  1. Set your username:
    git config --global "FIRST_NAME LAST_NAME"
  2. Set your email:
    git config --global ""

Configure repository-specific values

To configure repository specific values, do the following:

  1. Change directory to the root of the repository.
  2. Run the following command:
    git config "FIRST_NAME LAST_NAME"
  3. Run the following command:
    git config ""
  4. Verify your configuration by display your configuration file:
    cat .git/config

Mercurial username/email configuration

If you are using TortoiseHg in Windows, do the following to set global repository values:

  1. Right-click in your Desktop to open the context menu.
    The system displays the right hand context menu:
  2. Click the Hg Workbench item.
    The system opens the TortoiseHg Workbench application.

  3. Choose File > Settings to open the TortoiseHg Settings dialog.
  4. Locate the Commit section on the left hand side and click it.
  5. Fill in the Username value using the following format:
    firstname lastname<email>

    When done the dialog looks similar to this:
  6. Press OK to save your changes.

For Mac OS X and Linux systems do the following to set global repository values:

  1. Edit the Mercurial configuration file ~/.hgrc (installed by MacPorts) using your favorite editor.
  2. Specify a username value.
    When you are done, the configuration file looks something like this:

    # Name data to appear in commits
    username = Mary Anthony <>
  3. Save and close the file.
Configure repository-specific values

If you are using TortoiseHg in Windows, do the following:

  1. Start TortoiseHG.
  2. Right click your repository and choose Settings.
    The system displays the TortoiseHG Settings dialog with the NAME repository settings tab active.
  3. Press Edit File.
  4. View your current repository configuration.

  5. Change the username value to the value you want to use for that repository.
    When you are done you should see something similar to the following:

    # Name data to appear in commits
    username = Mary Anthony <>
  6. Press Save to close the editor.

  7. Press OK to close the settings dialog.

If you are using Mac OS X or a Linux OS, do the following:

  1. Open a terminal window.
  2. Edit the Mercurial global configuration file (REPO_INSTALLDIR/.hg/hgrc).
  3. Add the following line to the UI section:

    ssh = ssh -C

    When you are done the file should look similar to the following:

    # Name data to appear in commits
    username = Mary Anthony <>
    ssh = ssh -C
  4. Save and close the file.

Alias configuration

Only a user with admin permissions for repository can create an alias configuration. An alias is just for that repository; other repositories do not share that alias. Aliases are case sensitive, to alias commits from as well as FOO@BAR.COM, you must create two separate aliases. For example, let's assume you used to be and you used that as your DVCS username. Now, you switched to a different email address and updated your Bitbucket account accordingly. Commits under the old email address are no longer linked to you:

Identify the Author you want to alias and find the author's committer string. To do this:

  1. Locate the Author in the Commits list.
  2. Click on the corresponding Commit.
    The Commit panel appears.
  3. Click on the raw commit link.
    The raw commit string passed to Bitbucket displays.
  4. Locate the User section and select the information in it.
  5. Copy to your clipboard.

To make sure Bitbucket knows that these old commits were yours, go to the repository administration section and create a custom alias that maps to your account.

  1. Log in as the repository administrator.
  2. Go to the repository where you want to set up an alias.
  3. Go to the repository  settings.
  4. Click Username aliases.
  5. Enter the Username for the Bitbucket user you want to appear as the Author.
    In this example, I want the tutorials user to show up for my other users. So, I enter tutorials.

  6. Enter the Alias for this user.
    Paste the User data from the raw commit.

  7. Press Add alias.

After this alias configuration, Bitbucket correctly links your commit for this repository:

Last modified on Nov 8, 2017

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.