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.

Who can use this?


When to merge users

Merging users is important to keep your report data accurate.

Merge users when:

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

Tip: Flow can notify you when new users are added to Flow or when Flow finds users you might want to merge. Learn more about signing up for email alerts.

To 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.

Regularly check your merge suggestions to make sure your data remains accurate.

back to top

How to merge user aliases

Flow has a dedicated user merge page to help you navigate potential and recommended merges.

From the user merge page, there are three options for merging users: addressing merge suggestions, manually merging, and auto-merging.

back to top

Merge suggestions

The Merge suggestion tab surfaces users who are likely the same person and recommends them for merging. 

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

In the Merge suggestions tab of the Merge users page, Merge suggestions are displayed alphabetically in the suggestions list on the left. The target user and suggested merges are on the right.

If the suggestion is accepted, the suggested users will be merged into the target user. The first user on the suggestions 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 on the left whose merge suggestion 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.

back to top

Merge suggestion alerts

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

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.

Use admin alerts to have an email alert sent to you when new users are added or when Flow finds users you might want to merge.

back to top

Merging large numbers of users

It is common to have a lot of merge suggestions.

Use quick filters to resolve suggestions more easily.

  • 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 filter 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

Manually merge users when you want to merge a few users. This is useful when you have new merge suggestions or new aliases introduced to Flow.

To manually merge a user:

  1. Click the All users tab.
  2. Search for the user you want to merge.
  3. Click and drag the user to the Select a target user area to the right of the page. This is your target user for merging aliases.
  4. Find the other users you want to merge with the target user. Click and drag those users into the Select one or more aliases area to the right. These users will be merged into the target user.
  5. Review the users and click Merge. The aliases appear under the target user in the users list.
  6. Click Save to apply the merge to the user selected for merging.

View all aliases associated with a user on the User detail page under the Aliases tab.

back to top


Auto-merge automatically merges aliases to target users. Flow bases auto-merges on the sign-in email address of the user or other 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 auto-merge if desired.

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 auto-merge:

  1. Click Settings in Flow's top navigation bar.
  2. In the left navigate under User Management, click Users page.
  3. Click Merge users in the top right of the Users page.
  4. On the Merge users page, click the Preferences tab.

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

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

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

Sign in 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.

Important: If Flow incorrectly auto-merges users, manually merge or unmerge them.

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 have the same name.

back to top

Reviewing merge suggestions

Review merge suggestions to make sure your users’ aliases are correct. For example, you may notice an engineer’s work isn’t accurately represented in a report. Check their aliases to make sure their aliases are merged correctly so their work is represented accurately in reports.

To review a user’s merged aliases:

Click Settings in the top navigation bar.

  1. In the left navigation under User Management, click Users.
  2. Click the Merge users button in the top right corner of the Users page. 
  3. Click the All users tab.
  4. Use the user list to review users or search for the user you want to review.
  5. Click the arrow beside the user’s name to view the aliases for that user.

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 a recognizable 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 users that don’t belong, 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.

back to top

Unmerge users

The All users tab shows your users and their merged aliases. If an alias appears to be merged into the wrong user, unmerge them. The unmerged alias becomes a user and appears in the user list.

To unmerge users and aliases:

  1. Click and drag the user to the Select a target user area to the right of the All users page.
  2. Click the Unmerge icon next to the alias you want to unmerge. This means the chosen alias becomes its own user.
  3. In the popup box, review your selection and click Unmerge. The unmerged alias now appears as a user in the user list.

back to top

If you need help, please contact Pluralsight Support.