Platform settings
The platform Settings page holds what applies to the whole installation: the addresses Merge Pilot is reached at, which sign-in methods companies may use, how long a sign-in lasts, and the license. Company settings are on each company's own page.
- Where: Administration → Settings.
- Who: platform admins only, and only in a signed-in session (API tokens cannot read or change these settings).
- Tabs: General, Sign-in and License. Each tab saves on its own.
- Every save is recorded in the audit log as
update_settings, with the fields that changed.
General
The three addresses Merge Pilot uses to build links. Each must be an http:// or https:// URL with a host.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Application URL | The address your VCS and tracker call: webhooks, the GitHub App's events and change management setup use it. It must be reachable from them. Changing it points every company's webhooks at the new address in the background | Empty | An http(s):// URL, required: saving it empty is refused | Platform admin | app_url |
| Public URL | The address people's browsers use for Merge Pilot's server: sign-in redirects go here, including the OpenID Connect redirect URI and the SAML endpoints given to identity providers | Empty (the Application URL is used) | An http(s):// URL, or empty | Platform admin | public_url |
| Frontend URL | The address of the web app, where people land after signing in | Empty (the Public URL, else the Application URL) | An http(s):// URL, or empty | Platform admin | frontend_url |
The redirect URI of every OpenID Connect provider and the SAML metadata, entity ID and assertion consumer service URL of every SAML provider are built from the Public URL (or the Application URL when it is empty). After changing it, update them at each identity provider. See Identity providers.
Company admins can read these three addresses (they build webhook URLs from them), but cannot change them.
Sign-in
Sign-in methods
What companies may use. Each company turns on what it needs on its own Sign-in tab (Sign-in). A method turned off here is off for every company, and sessions signed in with it end at their next renewal.
| Setting (label in the UI) | What it does | Default | Who can change it | API field |
|---|---|---|---|---|
| Merge Pilot passwords | Accounts created in Merge Pilot sign in with a user name and password. Platform admins always sign in with their password, even when this is off | On | Platform admin | sign_in_methods.local |
| Company directories (LDAP) | Each company's own LDAP directory | On | Platform admin | sign_in_methods.ldap |
| OpenID Connect | Keycloak, Entra ID, Okta and other OIDC identity providers | On | Platform admin | sign_in_methods.oidc |
| SAML 2.0 | ADFS and other SAML identity providers | On | Platform admin | sign_in_methods.saml |
| GitLab accounts | Signing in with GitLab through a company's connection | On | Platform admin | sign_in_methods.gitlab |
| GitHub accounts | Signing in with GitHub through a company's GitHub App | On | Platform admin | sign_in_methods.github |
Each is a switch (true or false). Save with Save sign-in methods.
Sessions
How long a sign-in lasts: the access token renews quietly until the refresh token runs out, then people sign in again. Identity providers may end a session sooner (see Sign-in).
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| JWT access token lifetime | How long one access token is valid before the browser renews it | 15m | 1 minute to 24 hours. A duration such as 15m, 12h or 1h30m; a whole number of days such as 1d is also accepted | Platform admin | jwt_access_duration |
| JWT refresh token lifetime | How long a session lasts without signing in again | 7d | 1 hour to 2160 hours (90 days). A duration such as 12h or 168h, or whole days such as 7d | Platform admin | jwt_refresh_duration |
A field left empty keeps its stored value. Save with Save settings. The new lifetimes apply to tokens issued after the save.
License
The license tab shows the license and activates or removes it. Webhooks from your VCS and tracker are processed only while a valid license is active; without one they are refused.
Grace period
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Grace period after the license expires (days) | How long Merge Pilot keeps working after its license expired. During it, merge requests are processed as usual and every page says until when. After it, webhooks from your VCS and tracker are refused and background work waits until a license is installed | 14 | 0 (none) to 90 | Platform admin | license_grace_days |
The grace period works for online licenses and license files alike, counted from the expiry the license carries. When it starts, company admins get the License expiring notification saying that the license expired and until when Merge Pilot keeps working (see Events).
Installing a valid license (online or a file) sets every company's webhooks up again, since the VCS may have turned off those it could not deliver.
License status
| Field | Shows |
|---|---|
| Mode | online or offline: how the license was activated |
| Status | Valid or Invalid |
| Plan | The licensed plan |
| Expires | The expiry day, when the license has one |
| Last checked | When the license was last checked: the last answer of the license server for an online license |
| Fingerprint | This installation's fingerprint |
| Reason | Why the license is invalid, when it is |
When no license is active, the tab says so and offers the two ways to activate one.
Merge Pilot believes only what the license itself proves: the signed offline license file, or the signed answer of the license server.
- Online license. Merge Pilot asks the license server when it starts, when a license key is activated, and when a platform admin selects Check now on the status card. The answer stays in force until the license's expiry day, also while the license server cannot be reached; it cannot be revoked in the meantime. In the last day before the expiry Merge Pilot asks again, so a renewed license continues without a gap. If the license server cannot be reached by the expiry, Merge Pilot is unlicensed until it can be. While the license is not valid (expired, suspended, not found), Merge Pilot asks every hour, so a renewal or reactivation is picked up without Check now.
- Offline license. Merge Pilot never contacts the license server. The file is valid until the expiry day in it. Check now checks the file again on the server.
A license without an expiry day does not expire. When Check now cannot reach the license server, the message is the license service could not be reached; the license stays as it was until its expiry day.
Besides the messages below, Reason can say:
| Reason | Why | What to do |
|---|---|---|
| the license has not been checked with the license service yet | An online license has no signed answer from the license server yet, for example right after an upgrade while the server cannot be reached | Select Check now once the license server can be reached, or activate the key again |
| the stored license check could not be verified | The stored license data does not match a signed answer for this license and installation | Activate the license key again |
Activating and removing
| Setting (label in the UI) | What it does | Who can change it |
|---|---|---|
| License API key (card API key) | The key Merge Pilot uses with the license server. Required for online activation. Shown as Configured or Not configured; the value is never shown again | Platform admin |
| License key (card Online license) | Activates a license online with Activate | Platform admin |
| License file (card Offline license) | Upload license file activates a signed offline license file (.json), for environments without internet access | Platform admin |
| Remove license | Removes the active license after a confirmation. Webhook processing stops until a new license is activated | Platform admin |
A key or file that is refused leaves the current license as it was. The message says why:
| Message | Why | What to do |
|---|---|---|
| the license was refused: license key not found (or license expired, license is not active) | The license server does not accept the key | Check the key you entered; ask CloudNativeWorks about an expired or inactive license |
| the license key is already activated on as many instances as it allows: … | The key is in use on its maximum number of instances | Deactivate it on an instance that no longer needs it, or ask for more activations |
| set the license API key first, then activate the license key | Online activation needs the license API key | Save the key on the API key card first |
| the license service could not be reached; try again later, or activate with an offline license file | The license server did not answer, answered with an error of its own, or sent an answer that is not signed with CloudNativeWorks' key | Try again later, or use an offline license file |
| the license was refused: invalid license file format (or invalid license signature) | The uploaded file is not a license file as delivered, or was changed | Upload the file exactly as you received it |
| the license file expired on YYYY-MM-DD: ask for a renewed license file | The offline license file has expired | Ask for a renewed file |
License actions are recorded in the audit log as set_license_api_key, activate_license, check_license and deactivate_license.