Roles and users
Every person who signs in to Merge Pilot has one account with one role. The role decides which pages they see and what they may change. Every role except the platform admin belongs to exactly one company and acts on that company only.
The five roles
| Role (label in the UI) | API value | Belongs to | In short |
|---|---|---|---|
| Platform admin | platform_admin | No company | Runs this Merge Pilot: every company, the platform settings and the license |
| Company admin | company_admin | One company | Administers one company: connections, projects, users, settings and policies |
| Policy manager | policy_manager | One company | Maintains the company's change policies and approver pools |
| Auditor | auditor | One company | Reads everything of the company, including the audit log; changes nothing |
| User | user | One company | Works with changes: views them and votes when eligible |
What each role may do
| Action | Platform admin | Company admin | Policy manager | Auditor | User |
|---|---|---|---|---|---|
| Platform Settings (addresses, sign-in methods, session lifetimes, license) | Yes | No | No | No | No |
| Create and remove companies | Yes | No | No | No | No |
| Turn a company off or on | Yes | No | No | No | No |
| See every company | Yes | Own company | Own company | Own company | Own company |
| Company settings, connections, projects, sign-in, directory, identity providers | Yes | Yes | No | Read only (company settings through the API: the company page is for administrators) | No |
| Users page: create, edit, deactivate, set temporary passwords | Every company | Own company | No | No | No |
| Make someone a platform admin, move a person to another company | Yes | No | No | No | No |
| Change policies and approver pools | Yes | Yes | Yes | Read only | Read only |
| Decide reviewed changes to policies, pools and vulnerability exceptions | Yes | Yes | Yes | No | No |
| Decide reviewed changes to sign-in, the directory, identity providers, risk settings and personal tokens | Yes | Yes | No | No | No |
| Audit log and compliance report | Yes | Yes | No | Yes | No |
| People directory (who can be picked for pools) | Yes | Yes | Yes | Yes, without emails | No |
| Service API tokens of the company | Yes | Yes | No | No | No |
| Merge requests, change approvals, votes | Yes | Yes | Yes | Read only | Yes |
"Reviewed changes" exist only in companies that turned on Review control changes (Company → Governance tab). A change then waits until a second person who may decide it approves it; see Four-eyes review.
The auditor is read-only
An auditor may read every page of their company, but every request that changes something is refused with this role can only read. The exceptions change nothing outside the auditor's own account:
- changing their own password, signing out, and Sign out everywhere;
- their own profile (display name, language), linking and unlinking an identity provider or a GitLab or GitHub account, and their own personal API tokens (which act as an auditor too, so they only read);
- trying a policy against merge requests, the monitoring report and project evidence (these compute results and store nothing).
API tokens with the auditor role are read-only in the same way.
Things nobody can do to themselves
- Change their own role.
- Deactivate their own account.
- Demote or deactivate the last active platform admin. Make someone else platform admin first.
The first platform admin
A new installation has one platform admin, user name admin. It must choose a new password at its first sign-in; until then every other request is refused. This account is created only when no platform admin exists, so renaming or replacing it does not bring it back.
The Users page
Administration → Users lists the people the signed-in admin manages:
- a platform admin sees every account of every company; the company is shown next to the role;
- a company admin sees the accounts of their own company, without platform admins.
Search matches the user name, email and display name. The list can be sorted by Username, Display name, Role and Last login.
| Column | Shows |
|---|---|
| Username | The account's user name |
| Display name | The name shown across Merge Pilot |
| The account's email | |
| Role | The role; for a platform admin's view, also the company |
| Source | How the account signs in: Merge Pilot (created on this page), LDAP, OpenID Connect, SAML, GitLab or GitHub (API auth_source: local, ldap, oidc, saml, gitlab, github). role from IdP marks a role set by an identity provider, role from directory one set by the company directory's groups |
| Linked accounts | The GitLab or GitHub accounts the person linked. Not linked: they cannot be assigned a change approval or vote until they link one in My profile |
| Status | Active or Inactive; Password change pending while they sign in with a temporary password |
| Last login | When they last signed in (Never if not yet) |
The Users page needs a signed-in session: API tokens cannot create or change users.
Add user
Add user creates a local account, which signs in with a user name and password.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Username | The name used to sign in | — | 3 to 50 characters: letters, digits, ., _ or -, starting with a letter or digit. Stored in lower case. Unique across the installation | Platform admin, company admin | username |
| Display name | The name shown across Merge Pilot | — | Required | Platform admin, company admin | display_name |
| The person's email | — | A valid email; unique within the company | Platform admin, company admin | email | |
| Temporary password | The first password. The person must replace it at their first sign-in | — | 12 to 72 characters, not equal to the user name | Platform admin, company admin | password |
| Role | The person's role | User | Platform admin (offered to platform admins only), Company admin, Policy manager, Auditor, User | Platform admin, company admin | role |
| Company | The company the person belongs to | — | Any company. Shown to platform admins only, and not for the platform admin role. A company admin's users always belong to their own company | Platform admin | company_id |
| Tracker account | The person's user name, email or account ID in the company's tracker (Jira). Set it when the company's matching rule on the People tab does not find them | Empty (found by the company's rule) | Any text, stored in lower case; one person per account within a company. Not for platform admins | Platform admin, company admin | tracker_account |
Edit user
The pencil icon opens Edit user. It has the same fields without the password, plus Status (Active or Inactive).
- Accounts from outside (LDAP, an identity provider, GitLab or GitHub) take their user name, display name and email from where they sign in. Only their role, status and tracker account can be changed here, and they stay in their company.
- A role from an identity provider cannot be changed here: it comes from the person's groups at every sign-in. Change the groups or the provider's role mapping (see Identity providers).
- A role from the company directory (role from directory) cannot be changed here either: change the person's directory groups or the directory's role mapping. When the directory is turned off or its role mapping removed, the role can be edited here again (see The account).
- Making someone platform admin removes their company, tracker account and linked GitLab and GitHub accounts. Only local accounts can become platform admins.
- Moving a person to another company (platform admins only, local accounts only) removes their linked GitLab and GitHub accounts and their tracker account. Their open change approvals in the old company are dealt with as when they are deactivated (see Deactivate a user).
- Setting Status to Inactive deactivates the person as the bin icon does, including what happens to their open change approvals.
A new role or company applies at once: the person's existing sessions and personal API tokens stop working, and they continue after the session renews or they sign in again.
Making someone platform admin, or moving them to another company, also ends what Merge Pilot tracked of the repository access they got by joining through Merge Pilot in their old company, and of the GitLab project access tokens and deploy tokens Merge Pilot created for them there. The access and the tokens stay on GitHub or GitLab and may still work; that company's admins see them under People (tokens: Tokens created through Merge Pilot), to remove the access there and revoke or dismiss the tokens.
Set a temporary password
The key icon opens Set a temporary password, for local accounts only (for other accounts the password is managed by their source). The password must be 12 to 72 characters and not equal to the user name. The person is signed out everywhere and must choose a new password at their next sign-in.
Deactivate a user
The bin icon deactivates the account after a confirmation; Edit user → Status → Inactive does the same. The person can no longer sign in or use Merge Pilot, and every session ends at once. The account is kept: reactivate it later with Edit user → Status → Active.
Their open change approvals are assigned again or kept with a warning, as the company's When an assignee is deactivated setting says (Approvals tab). When nobody else may take one, it is also unassigned in the tracker, with a comment saying why.
Deactivating cleans only Merge Pilot's records: the repository access they got by joining through Merge Pilot, and the GitLab project access tokens and deploy tokens Merge Pilot created for them, are no longer tracked. Merge Pilot does not remove any access or revoke any token on GitHub or GitLab: the company's admins see what may still exist under People (tokens: Tokens created through Merge Pilot), remove the access there, and revoke the tokens from that list.
Passwords
The same rules apply wherever a password is set: on the Users page, on My profile and at a forced change.
| Rule | Value |
|---|---|
| Minimum length | 12 characters, or more under the company's password policy (Company → Sign-in → Password policy; see Sign-in) |
| Maximum length | 72 bytes: 72 characters in English letters, fewer with letters outside English. The minimum counts characters |
| Not allowed | The user name (compared without regard to case); when changing your own, the current password |
- Only local accounts have a Merge Pilot password. LDAP accounts use their directory password; identity provider, GitLab and GitHub accounts have none.
- A password an admin sets is temporary: the person must replace it at their next sign-in. Until then, the Set a new password page is the only page they can use (Save and continue or Sign out).
- Changing a password, your own or someone else's, ends every other session of that account.
My profile
Every signed-in person reaches My profile from the account menu.
| Card | What it shows or does |
|---|---|
| Account information | Username, Email, Display name, Role, Sign-in method (the account's source) and Language. The language is saved to the account; English is the only language today |
| Password | For local accounts only: Current password, New password, Confirm new password, then Change password. Other sessions are signed out |
| Sessions | Sign out everywhere ends every session of the account on every browser and device, including this one. Signing out ends this browser only |
| Single sign-on | The company's identity providers. Link connects one to this account; Unlink removes it. Shown only when the company has identity providers |
| Stand-ins | Who approves in the person's place while they are away |
| API tokens | The person's personal API tokens (see API tokens) |
| Linked VCS accounts | The person's GitLab and GitHub accounts. Link account sends them to the provider to authorize; back on My profile, the page confirms the link and only then is it saved. Connections that cannot be linked yet are listed with the reason (their sign-in switch is off, or their client ID or secret is missing). Unlink removes an account. Linking records only which GitLab or GitHub user the person is: Merge Pilot keeps no access in their name. Change approvals are assigned and votes accepted only once Merge Pilot knows the person's GitLab or GitHub account |
| Tracker account | The person's account in the company's tracker, as an admin set it on the Users page |
| Notifications | Which emails Merge Pilot sends the person themselves (as a change approval's assignee or approver, a change's author, a company admin, or about their account), one switch per event. See Personal notifications |
A platform admin belongs to no company, so their profile shows no linked VCS accounts, no tracker account, no stand-ins and no API tokens.
Unlinking a sign-in method
Unlinking an identity provider is refused when:
- it is the account's only way to sign in (link another one first);
- the provider gives the account its role (an admin manages the account instead).
Unlinking a GitLab or GitHub account is refused when it is the account's only way to sign in. Once unlinked, change approvals are no longer assigned to the person through that account and they cannot sign in with it. For GitHub, Merge Pilot also asks GitHub to withdraw the person's whole authorization of the Merge Pilot app, which ends every token GitHub gave it for them. When GitHub refuses (for example a token it no longer knows), the account is unlinked anyway and the audit log says the withdrawal failed. Unlinking needs a signed-in session: an API token cannot do it.
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →