Sign-in
Merge Pilot offers six ways to sign in. The platform decides which of them companies may use; each company then turns on the ones it needs. A person always signs in to one account, whichever way they use.
Sign-in methods
| Method | API value | How the person signs in | Accounts it creates |
|---|---|---|---|
| Merge Pilot password | local | User name and password of an account made on the Users page | None (admins create them) |
| Company directory (LDAP) | ldap | Directory user name and password, checked against the company's LDAP | An account with the User role at the first sign-in (details) |
| OpenID Connect | oidc | The company's OIDC identity provider (Keycloak, Entra ID, Okta and others) | Depends on the provider's New people setting (details) |
| SAML 2.0 | saml | The company's SAML identity provider (ADFS and others) | Same as OpenID Connect |
| GitLab account | gitlab | Continue with GitLab through one of the company's GitLab connections | Only when the company lets anyone in (see below) |
| GitHub account | github | Continue with GitHub through the company's GitHub App | Same as GitLab |
Two levels: platform and company
A method works for a company only when it is on at both levels:
- Platform: Settings → Sign-in → Sign-in methods (Platform settings). Every method is on by default. A method turned off there is off for every company, and the company's Sign-in tab shows Turned off on the platform.
- Company: the company's Sign-in tab (Company → Sign-in). Company admins and platform admins change it.
Turning a method off at either level also ends the sessions that were signed in with it: they are refused at their next renewal, and the person must sign in another way.
The company's Sign-in tab
The tab has five cards. The settings on it are saved with the company page's save button, except identity providers, which save themselves. API tokens cannot change these settings.
Merge Pilot passwords
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Sign in with a user name and password | Accounts created on the Users page sign in with their Merge Pilot password | On | On or off | Company admin, platform admin | sign_in.local |
Changes that would lock people out
Any change to the company's sign-in settings or to its company directory (not only turning passwords off) first checks who would lose every way in: the company's active people who can sign in now and could not after the change. A way in is a Merge Pilot password, the directory, an enabled identity provider (a linked account, or an invitation to link one that has not expired) or a linked GitLab or GitHub account while signing in with it is on. Each counts only where the platform allows that method.
- When you are one of them, saving is refused (you would no longer be able to sign in: link an identity provider or VCS account in My profile first, or keep your way of signing in on).
- Otherwise the others are named and Merge Pilot asks Save a sign-in change that locks people out? before saving. Save anyway saves it (API: a
409with codesign_in_lockout; send again withconfirm_lockout: true).
Inviting someone to link an identity provider
Someone who signs in only with a password cannot link an identity provider from My profile once passwords are off, and a provider that creates no accounts does not let them in. On the Users page, a company admin selects the person's Invite to link an identity provider account button and picks the provider. The person's next sign-in with that provider links to their account when the provider's email is the account's email. The invitation stands for 14 days; the button shows a pending one. API: POST /api/v1/users/{id}/sso-invite with provider_id (DELETE withdraws it). Audit: sso_link_invited, then sso_identity_linked.
Company directory (LDAP)
The directory's own settings, including its on/off switch, are described on Company directory (LDAP).
Identity providers
The company's OpenID Connect and SAML providers. Each has its own Enabled switch. See Identity providers.
Signing in with GitLab or GitHub
Who may use the "Sign in with GitLab/GitHub" button for this company. The card lists the company's active GitLab and GitHub connections with their state: Sign-in and linking on, Sign-in and linking off, or Turned on, but no OAuth client is set. Each connection turns signing in and linking accounts on in its own settings; the choice below says who may sign in.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Signing in with GitLab or GitHub | Who may sign in with a GitLab or GitHub account | Only accounts that exist here | See the options below | Company admin, platform admin | sign_in.vcs |
| Email domains | Shown for Anyone on our GitLab or GitHub. Only accounts whose email ends in one of these get in. Empty lets in everyone on your GitLab or GitHub | Empty | Comma-separated email domains, such as acme.com, acme.co.uk | Company admin, platform admin | sign_in.vcs_email_domains |
The options:
- Off (
off): nobody signs in with GitLab or GitHub. People still link those accounts in My profile, so Merge Pilot knows who they are there. - Only accounts that exist here (
linked): people whose Merge Pilot account has linked that GitLab or GitHub account. Nobody new gets in. - Anyone on our GitLab or GitHub (
open): a first sign-in creates a Merge Pilot account with the User role. Limit it to your email domains.
How a GitLab or GitHub sign-in finds the account:
- The account is the one that linked this GitLab or GitHub account on this connection. Accounts are never matched by user name or email.
- A new account takes the GitLab or GitHub login as its user name. When another account of the company already has that name, a suffix is added (
alice-gitlab, thenalice-gitlab-2, and so on). In a company with its directory turned on, the suffix is always added, because plain names belong to the directory. - A new account takes the email GitLab or GitHub gives (GitHub: the profile's public email, or else the verified primary email). GitLab's email is used only when GitLab reports it confirmed: without that, no account is created.
- When the email from GitLab or GitHub is already used by another account of the company, the sign-in is refused. That person signs in with their existing account and links GitLab or GitHub in My profile.
- GitHub shows its account picker at every sign-in and link, so someone signed in to GitHub with another account can choose the one linked here. GitLab uses the account signed in to GitLab in that browser: to use another, sign out of GitLab first.
With Anyone on our GitLab or GitHub and no email domains, a connection to gitlab.com or github.com would let anyone in the world create an account in the company. The tab warns about this.
Finding this company on the sign-in page
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Email domains of this company | People who type a work email with one of these domains on the sign-in page are brought to this company's ways to sign in | Empty | Email domains, such as acme.com. A domain belongs to one company only | Company admin, platform admin | sign_in.domains |
| Show this company in the sign-in page's company list | Lists the company under Or choose your organization | On | On or off | Company admin, platform admin | sign_in.listed |
A company is listed only when it is active and offers more than Merge Pilot passwords (a directory, an identity provider, or GitLab or GitHub sign-in).
Four-eyes review
When the company turned on Review control changes (Company → Governance), saving a change to "How people sign in" or to the company directory does not apply it. It waits until another company admin or platform admin approves it. See Four-eyes review.
The sign-in page
- The person types their Work email or user name and selects Continue.
- Text without
@is a Merge Pilot user name: the password form opens. - An email whose domain belongs to a company (Email domains of this company) opens that company's ways to sign in.
- Any other email opens the password form, or says Merge Pilot passwords are turned off when the platform turned them off.
- Text without
- Instead, they can pick their company under Or choose your organization. The browser remembers the last company chosen.
- The company's page shows a button for each identity provider and each GitLab or GitHub connection that may sign people in (Continue with …), and the password form when passwords or the directory are on. With the directory on, it says Use your directory (LDAP) user name and password.
- Administrator? Sign in with a Merge Pilot account opens the plain password form, for platform admins and other local accounts.
When a company has nothing turned on, the page says so and asks the person to contact an administrator.
Password sign-in order
A user name and password are first checked against local accounts. When no local account matches and a company was chosen, they are checked against that company's directory, if the directory is on at both levels.
Platform admins always sign in
Platform admins sign in with their Merge Pilot password even when Merge Pilot passwords is turned off on the platform, so nobody is locked out. Such a sign-in is recorded in the audit log as break_glass_login. Platform admins can sign in only with their password: they have no company, so no directory, identity provider or GitLab or GitHub account.
Password policy
Company → Sign-in → Password policy makes Merge Pilot passwords and sign-in lockouts of the company's people stricter. Values looser than the defaults are refused.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Minimum password length | The shortest Merge Pilot password a person, or an admin for them, may set from now on, in characters | 12 | 12 to 72 | Company | Company admins, platform admins | password_policy.min_length |
| Failed sign-ins before a lockout | Failed sign-ins for one user name from one address within 15 minutes that lock that address out | 10 | 3 to 10 | Company | Company admins, platform admins | password_policy.max_attempts |
| Lockout (minutes) | How long that lockout lasts | 15 | 15 to 1,440 | Company | Company admins, platform admins | password_policy.lockout_minutes |
The lockout policy belongs to the account, not to the sign-in request: naming another company when signing in cannot loosen it. When accounts of that name exist in several companies, the strictest of their policies applies.
A password is at most 72 bytes long: 72 characters in English letters, fewer when it has letters outside English.
Failed sign-ins
Merge Pilot slows down and locks out password guessing. A company can make the lockout stricter (see Password policy); it can never be looser than this.
| Protection | Rule |
|---|---|
| Lockout per address and account | 10 failed sign-ins (or the company's number) for one user name from one client address within 15 minutes lock that address out of that account for 15 minutes (or the company's lockout). Other addresses are not affected, so an attacker locks out only themselves. The message says how many minutes are left |
| Delay per account | After 5 failed sign-ins of one user name within 15 minutes, from any addresses, each further attempt must wait: 1 second, doubling with each failure, up to 30 seconds. The account is never locked |
| Rate limit per address | Sign-in attempts from one client address are limited per minute (30 by default), counted once for the whole installation |
Directory accounts count failed sign-ins under the account's own name, whatever form the person types (for example their user name or their account name). A locked account is refused even with the right password until the lockout ends.
Each refused password sign-in is recorded in the audit log as login with status failure and the reason, and a lockout as login_locked (see Audit log). A successful sign-in clears the counters. A right password for a directory account that is in none of the allowed groups is refused, but it does not count as a failure. Neither does a sign-in the company directory could not check (it cannot be reached, or it refused Merge Pilot's bind user): it is answered the company directory cannot be reached: try again later or ask your administrator, and recorded as ldap_login with the reason.
Sessions
A sign-in starts a session in that browser.
- Access token: renews quietly in the background. Lifetime: JWT access token lifetime (default 15 minutes).
- Session: lasts JWT refresh token lifetime (default 7 days) unless something ends it sooner. Both are set in Platform settings.
- At most 20 sessions per person: a 21st sign-in ends that person's oldest session.
When a session renews
Each renewal checks again that the person may still sign in the way they did:
| Signed in with | Checked at each renewal |
|---|---|
| Merge Pilot password | Passwords are still on for the company and the platform |
| Company directory | The directory is still on; the person is still found by the user filter and is still in an allowed group |
| OpenID Connect, with a refresh token from the provider | The provider is still enabled; the provider still accepts the refresh token; when it sends new groups, the person is still in Only these groups |
| OpenID Connect without a refresh token, or SAML | The provider is still enabled. The session ends after the provider's Sign in again after (hours) (default 8), or earlier when a SAML provider says so |
| GitLab or GitHub | GitLab or GitHub sign-in is still on for the company and the platform |
When a check fails, the session ends and the sign-in page says why, with a message such as your sign-in was withdrawn: sign in again or this way of signing in is turned off for your company. A session ended by an administrator or by a deactivation says so too (see When a session ends).
What ends sessions at once
- Deactivating a person ends all their sessions.
- Changing a person's role or company stops their current sessions; they continue after renewing, with the new role.
- Changing a password (their own or by an admin) ends every other session of the account.
- Deactivating a company stops the sessions of all its people.
- Sign out everywhere on My profile ends every session of the person, including the current one. Sign out ends only the current browser.
Error messages after GitLab, GitHub or identity provider sign-in
| Message | Cause |
|---|---|
| This company does not let people sign in with … | The method is off for the company or the platform |
| No Merge Pilot account has linked this account at … | The company allows only accounts that exist here, or the identity provider allows only linked people, and nobody linked this account |
| Only accounts with this company's email domains may sign in with … | The email is not in the allowed email domains |
| Your GitLab email is not confirmed. Confirm it in GitLab, then sign in again. | A first sign-in would create an account, and GitLab reports the account's email as not confirmed. Confirm the email in GitLab |
| Your account at … is not in a group that may sign in to this company | The person is in none of the provider's Only these groups |
| Another account of this company already has the email from … | Sign in with that account, then link the provider in My profile |
| This account at … is already linked to another Merge Pilot user | The outside account belongs to another person here |
| Your account is deactivated | An admin deactivated the account, or its company is inactive |
| This sign-in attempt expired or was already used | Start again from the sign-in page |
Related pages
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →