Merge users

Tags: Flow

Engineers use multiple identities to do their work. Merging these identities ensures the engineer's work is reflected holistically and accurately. The merge tool helps you merge these identities together. Learn more about aliases and what they are.

Who can use this?


When to merge users

Merging users is important for keeping report data accurate. 

Merge users when:

  1. You add a new team member to your organization. 
  2. You commit data under a different alias that has not been imported into Flow.  
  3. You add new data sources to Flow including integrations, repos, and PR projects.

You can also sign up to have an email alert you when new users have been added or when Flow has found some users that you might want to merge. 

Recommendations to keep your user data clean and limit the number of user merges you need to complete:

  • Use a consistent account to contribute to your Git host and ticket system. If you and your team create many new accounts, or use different Git identities to commit code, you will generate new aliases that will need to be merged to your apex user
  • Be aware of new integrations you add to Flow. Each new integration will generate a new alias for your users.  Watch out, especially, for open source repos. If your team is contributing to them, then you may need to import them, but think twice if you’re just curious.
  • Merge new aliases as soon as they have contributed to your Git host or ticket Integration. 

back to top

How to merge user aliases

Starting on your Flow home page, go to the top navigation bar and click Settings. Using the left navigation under User Management, click Users. Click Merge users in the top-right corner.

From here, there are three options for merging users.

back to top

Merge suggestions

The Merge suggestion tab surfaces users who are likely the same person and recommends them for merging. Use Merge suggestions to find users to merge and keep your user base clean. 

To view Merge suggestions, navigate to the Users page and click Merge users.

You are now on the Merge suggestions tab. Merge suggestions are displayed alphabetically in the merge suggestions list on the left. The target user and suggested merges are on the right.

The target user is the user into which the suggested users are merged. The first user on the list is selected and displayed on the right as the target user. The target user changes as you move through users in the merge suggestions list. 

To change the target user, click the user’s row in the merge suggestions list. Click on a different user or use the previous and next arrows to move through the merge users list without merging or rejecting merge suggestions. Previously selected suggestions appear in the Viewed tab.

To merge a suggestion:

  1. Click the user’s row on the left you want to view. 
  2. Review the selection on the right-hand side. 
  3. If the suggestion is correct, click Merge and next to merge the selection and continue to the next suggestion. 
  4. If the suggestion looks incorrect, click Reject and next and continue to the next suggestion. The merge suggestion is now rejected. 
  5. Use the Rejected tab to review the rejected suggestions. Rejected suggestions are not resurfaced as new merge suggestions.

You may see multiple users as merge suggestions for the target user. If one of the users should not be merged, click the X next to that user to exclude them from the merge.

Merge alerts

If you have Manage users & teams permissions, Flow alerts you when there are new merge suggestions. Learn more about administrative permissions.

When Flow finds new merge suggestions, an alert notification appears by the Settings icon in the top navigation. Find details about merge alert suggestions on Settings home under User health

Under User health, find:

  • Users to merge to see how many new merge suggestions are in Flow. 
  • Users in metrics to see the percentage of users with open merge suggestions, including new and viewed merge suggestions.

Click Merge users to navigate to the merge users page to address your open merge suggestions. After they are viewed, merged, or rejected, the merge users alert notification disappears.

Have an email alert sent to you when new users are added or when Flow finds users you might want to merge.

Tips for reviewing merge suggestions

What to look for when reviewing merge suggestions:

  • Do they appear to be the same user?
  • Has Flow selected the best user as the target user. The target user is the user who displays in the user list and reports after the merge is complete. A good target user:
    • Has a login    
    • May be included or excluded from metrics
    • Has an expected name and email address

You’re likely to see one of three things in merge suggestions:

  • The suggestion looks good.  All the users in the suggestion look like the same person, and the target user is the user you want in your reports. This should be most of the time.

  • The suggestion is wrong. The suggestion includes different people. This should be a rare case.

  • The suggestion is mostly correct.

    • Most of the users look like the same person, but maybe there are one or two that are not. 

    • Maybe they all look like the same person, but the one selected for the target user isn’t the best one for some reason.

When the suggestion is correct, click Save and Next.

When the suggestion is wrong, click Reject and next.

When things are mostly correct, use the workspace panel on the right to modify the suggestion before accepting it.

  • If there are some users that don’t belong, you can remove them from the merge. 
  • If there is a user that is better for the target user, you can set them as the target user.
  • To select a different target user, click Edit target user. Edits to the target user are saved when the merge is complete.

Merging large numbers of users

It is common to have a lot of merge suggestions. 

Use quick filters to resolve suggestions.

  • Contain default domain - To use this filter, you first need to set up your default domain under the Preferences tab on the merge user page. Once set up, this filter shows you only merge suggestions containing aliases with your company email address. 
  • Aliases created in the last 30 days - This list shows you any recently created aliases. This could help you locate new employees that recently started committing to your code base, and/or users that have recently been ingested from a new repo or Integration. 
  • Have multiple logins - This filter is helpful if you have enabled an SSO Integration and users may end up with multiple logins due to case-sensitive email addresses.

Use the Merging users column to sort users and address larger chunks of users first.

back to top

Manually Merging

This option will be best if you are trying to merge only a select few users, or if you want to check if there are any new aliases that were introduced to Flow that have yet to be merged.

Start by clicking the All users tab. Then click and drag the user (that you would like to merge other users into) to the target user drop zone as depicted below.

Select other users that you would like to merge using the check boxes, then click and drag them into the alias drop zone.

Then click Save to apply the merge to the user staged for merging.

You can see all aliases associated with a user on the User detail page under the Aliases tab.

back to top


Automerge automatically merges aliases to target users based on the user’s signin email address or user email addresses. Even when the username is different, aliases with the same email addresses will merge. Before enabling auto-merge, use  the Exclusion settings to exclude users from automerge. 

Tip: Auto merge only applies to users integrated after auto merge is enabled and does not affect past data. Set up auto merge before adding integrations and repos.

To enable automerge users, navigate to the Users page and select the Merge users button. 

From the Merge users page, select the Preferences tab. 

At the bottom of the Preferences tab, you will find the Exclusions tool and the Automerge tool. First, use the Exclusion settings to exclude users or types of users from automerge. Enter the exclusions and then toggle on automerge to exclude those users from automerge. 

For example if you want to automerge all users except undisclosed users, then enter ‘undisclosed’ in the Exclusions text field. Then toggle on automerge. All users except undisclosed users will be automerged in future integrations. 

Select how you want to merge your users. You can automatically merge users based on their signin email or all email matches. 

 Signin email match merges users and aliases with the same login email. All email matches merges users and aliases based on the user’s email address.  Once you have chosen how you want to merge users, Flow will automatically merge users for future integrations. 

back to top

Default domain and configurations

Setting up your preferences makes merging users easier.

Under the Preferences tab on the merge users page, set a preferred domain. When developers make commits, the user name of those commits may vary. Your default domain designates the domain of  the user name that is picked as the main user. If more than one user account is found for a person, Flow uses the default name to determine the correct account.  Initially, the default domain is based on the first administrator's email address. We recommend checking that this default is correct so you can easily merge users after your data is ingested.   

Next, set preferred integration for future merge suggestions. The merge suggestion tool looks for your company domain first. If no company name is found, it looks to your preferred Integration.

You can also include hidden users in the merge suggestions and preferences tabs. By default, these options are toggled off. We recommend you keep these options off. 

Excluding hidden users allows you to focus on merging users you’re interested in.  Later, you can periodically include hidden users in merge suggestions.  

Including hidden users helps you catch any users who should be merged with an already existing hidden user. Merging hidden users allows you to hide them and keep your user list focused on the users you’re interested in. Learn more about hidden users.

In the bottom section you can also adjust the following merge suggestion and auto merge configurations:

  • Exclude common words and emails from matching. You can edit the defaults and add any that are specific to your account. Make sure the toggle is on to exclude parameters based on the specified words.

  • Exclude first name matches - This can be helpful if there are multiple users that use the name “Chris” or “John”. 

Learn more about excluding users

back to top

If you need help, please email for 24/7 assistance.