Skip to main content
2 video tutorials

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​

MethodAPI valueHow the person signs inAccounts it creates
Merge Pilot passwordlocalUser name and password of an account made on the Users pageNone (admins create them)
Company directory (LDAP)ldapDirectory user name and password, checked against the company's LDAPAn account with the User role at the first sign-in (details)
OpenID ConnectoidcThe company's OIDC identity provider (Keycloak, Entra ID, Okta and others)Depends on the provider's New people setting (details)
SAML 2.0samlThe company's SAML identity provider (ADFS and others)Same as OpenID Connect
GitLab accountgitlabContinue with GitLab through one of the company's GitLab connectionsOnly when the company lets anyone in (see below)
GitHub accountgithubContinue with GitHub through the company's GitHub AppSame as GitLab

Two levels: platform and company​

A method works for a company only when it is on at both levels:

  1. 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.
  2. 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 doesDefaultAllowed valuesWho can change itAPI field
Sign in with a user name and passwordAccounts created on the Users page sign in with their Merge Pilot passwordOnOn or offCompany admin, platform adminsign_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 409 with code sign_in_lockout; send again with confirm_lockout: true).

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 doesDefaultAllowed valuesWho can change itAPI field
Signing in with GitLab or GitHubWho may sign in with a GitLab or GitHub accountOnly accounts that exist hereSee the options belowCompany admin, platform adminsign_in.vcs
Email domainsShown 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 GitHubEmptyComma-separated email domains, such as acme.com, acme.co.ukCompany admin, platform adminsign_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, then alice-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.
Public hosts

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 doesDefaultAllowed valuesWho can change itAPI field
Email domains of this companyPeople who type a work email with one of these domains on the sign-in page are brought to this company's ways to sign inEmptyEmail domains, such as acme.com. A domain belongs to one company onlyCompany admin, platform adminsign_in.domains
Show this company in the sign-in page's company listLists the company under Or choose your organizationOnOn or offCompany admin, platform adminsign_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​

  1. 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.
  2. Instead, they can pick their company under Or choose your organization. The browser remembers the last company chosen.
  3. 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.
  4. 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Minimum password lengthThe shortest Merge Pilot password a person, or an admin for them, may set from now on, in characters1212 to 72CompanyCompany admins, platform adminspassword_policy.min_length
Failed sign-ins before a lockoutFailed sign-ins for one user name from one address within 15 minutes that lock that address out103 to 10CompanyCompany admins, platform adminspassword_policy.max_attempts
Lockout (minutes)How long that lockout lasts1515 to 1,440CompanyCompany admins, platform adminspassword_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.

ProtectionRule
Lockout per address and account10 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 accountAfter 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 addressSign-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 withChecked at each renewal
Merge Pilot passwordPasswords are still on for the company and the platform
Company directoryThe 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 providerThe 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 SAMLThe 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 GitHubGitLab 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​

MessageCause
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 companyThe 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 userThe outside account belongs to another person here
Your account is deactivatedAn admin deactivated the account, or its company is inactive
This sign-in attempt expired or was already usedStart again from the sign-in page

Video tutorials

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

Sign In and Create Your CompanyYouTube ↗
Sign In with GitLab and Link Your AccountYouTube ↗