When an engineer uses multiple identities to do their work, it is essential to get the identities merged, so that 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.
When to merge users
Merging users is super important, so it’s important to stay on top of it. You should always look to merge users when:
- You add a new team member to your organization.
- When you commit data under a different alias that has not been imported into Flow.
- When you add new data sources to Flow (integrations, repos, PR projects, etc.)
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.
- When you hire a new employee, ensure to merge their aliases as soon as they have contributed to your Git host and/or ticket Integration.
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 user.
The Merge suggestion tool is used when you don’t have a specific, problem user in mind, but want to keep your user base clean. The Flow system will review your user base and suggest users that are likely the same person.
You should check periodically for new suggestions, or configure the Admin alert emails to let you know if some come in.
Using the merge tool for merge suggestions.
There are three easy steps for reviewing suggestions:
First, select a suggestion from the list. Then review the selection and save or skip. You are looking at the list of users that Flow has suggested to merge together to see two things.
- Do they appear to be the same user?
- Has Flow selected the best user as the Target User. A target user is the user that will survive after the merge. You’re looking for:
- Whether the target user has a login and whether the merging users have logins.
- Whether the target user will be included or excluded from metrics.
- Whether the name and email for the target user are sensible.
You’re likely to see one of three things:
The suggestion looks good. All of the users in the suggestion look like the same person and the target user is fine. This should be most of the time.
The suggestion is junk. The suggestion has many different users on the right side. This should be rare.
The suggestion is mostly good.
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 looks good, just click Save and Next.
When the suggestion looks like junk, we recommended that you:
- Make a note of the distinct users the suggestion seems to represent. You’ll need to merge those manually. See Option 2, merging manually.
- Skip the suggestion.
When things are mostly right, use the workspace panel (the one on the right) to modify the suggestion before you accept 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.
Tips for merging large numbers of users
Use quick filters to take are of suggestions that matter most.
- Contain default domain - In order to use this filter you first need to set up your default domain under the Preferences tab. Once set up, this will show you only merge suggestions that contain aliases with your company email address.
- Aliases created in the last 30 days - This list will show you any alias that was recently created. 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.
Sort by the Merging users column and take care of the big ones first and then Select all on the rest. This works best if you set up your defaults settings (see Default configurations below).
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.
Automerge automatically merges aliases 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.
Note: Automerge is case insensitive and only affects future data. Automerge does not affect past data.
To 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.
Default domain and configurations
Under the Defaults tab, 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.
If you need help, please email firstname.lastname@example.org for 24/7 assistance.