Skip to main content
Video tutorial · 1:55

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 valueBelongs toIn short
Platform adminplatform_adminNo companyRuns this Merge Pilot: every company, the platform settings and the license
Company admincompany_adminOne companyAdministers one company: connections, projects, users, settings and policies
Policy managerpolicy_managerOne companyMaintains the company's change policies and approver pools
AuditorauditorOne companyReads everything of the company, including the audit log; changes nothing
UseruserOne companyWorks with changes: views them and votes when eligible

What each role may do​

ActionPlatform adminCompany adminPolicy managerAuditorUser
Platform Settings (addresses, sign-in methods, session lifetimes, license)YesNoNoNoNo
Create and remove companiesYesNoNoNoNo
Turn a company off or onYesNoNoNoNo
See every companyYesOwn companyOwn companyOwn companyOwn company
Company settings, connections, projects, sign-in, directory, identity providersYesYesNoRead only (company settings through the API: the company page is for administrators)No
Users page: create, edit, deactivate, set temporary passwordsEvery companyOwn companyNoNoNo
Make someone a platform admin, move a person to another companyYesNoNoNoNo
Change policies and approver poolsYesYesYesRead onlyRead only
Decide reviewed changes to policies, pools and vulnerability exceptionsYesYesYesNoNo
Decide reviewed changes to sign-in, the directory, identity providers, risk settings and personal tokensYesYesNoNoNo
Audit log and compliance reportYesYesNoYesNo
People directory (who can be picked for pools)YesYesYesYes, without emailsNo
Service API tokens of the companyYesYesNoNoNo
Merge requests, change approvals, votesYesYesYesRead onlyYes

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

ColumnShows
UsernameThe account's user name
Display nameThe name shown across Merge Pilot
EmailThe account's email
RoleThe role; for a platform admin's view, also the company
SourceHow 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 accountsThe 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
StatusActive or Inactive; Password change pending while they sign in with a temporary password
Last loginWhen 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 doesDefaultAllowed valuesWho can change itAPI field
UsernameThe 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 installationPlatform admin, company adminusername
Display nameThe name shown across Merge Pilot—RequiredPlatform admin, company admindisplay_name
EmailThe person's email—A valid email; unique within the companyPlatform admin, company adminemail
Temporary passwordThe first password. The person must replace it at their first sign-in—12 to 72 characters, not equal to the user namePlatform admin, company adminpassword
RoleThe person's roleUserPlatform admin (offered to platform admins only), Company admin, Policy manager, Auditor, UserPlatform admin, company adminrole
CompanyThe 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 companyPlatform admincompany_id
Tracker accountThe 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 themEmpty (found by the company's rule)Any text, stored in lower case; one person per account within a company. Not for platform adminsPlatform admin, company admintracker_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.

RuleValue
Minimum length12 characters, or more under the company's password policy (Company → Sign-in → Password policy; see Sign-in)
Maximum length72 bytes: 72 characters in English letters, fewer with letters outside English. The minimum counts characters
Not allowedThe 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.

CardWhat it shows or does
Account informationUsername, 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
PasswordFor local accounts only: Current password, New password, Confirm new password, then Change password. Other sessions are signed out
SessionsSign out everywhere ends every session of the account on every browser and device, including this one. Signing out ends this browser only
Single sign-onThe company's identity providers. Link connects one to this account; Unlink removes it. Shown only when the company has identity providers
Stand-insWho approves in the person's place while they are away
API tokensThe person's personal API tokens (see API tokens)
Linked VCS accountsThe 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 accountThe person's account in the company's tracker, as an admin set it on the Users page
NotificationsWhich 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.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Users and RolesYouTube ↗