Skip to main content

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 doesDefaultAllowed valuesWho can change itAPI field
Application URLThe 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 backgroundEmptyAn http(s):// URL, required: saving it empty is refusedPlatform adminapp_url
Public URLThe 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 providersEmpty (the Application URL is used)An http(s):// URL, or emptyPlatform adminpublic_url
Frontend URLThe address of the web app, where people land after signing inEmpty (the Public URL, else the Application URL)An http(s):// URL, or emptyPlatform adminfrontend_url
Changing the Public 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 doesDefaultWho can change itAPI field
Merge Pilot passwordsAccounts created in Merge Pilot sign in with a user name and password. Platform admins always sign in with their password, even when this is offOnPlatform adminsign_in_methods.local
Company directories (LDAP)Each company's own LDAP directoryOnPlatform adminsign_in_methods.ldap
OpenID ConnectKeycloak, Entra ID, Okta and other OIDC identity providersOnPlatform adminsign_in_methods.oidc
SAML 2.0ADFS and other SAML identity providersOnPlatform adminsign_in_methods.saml
GitLab accountsSigning in with GitLab through a company's connectionOnPlatform adminsign_in_methods.gitlab
GitHub accountsSigning in with GitHub through a company's GitHub AppOnPlatform adminsign_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 doesDefaultAllowed valuesWho can change itAPI field
JWT access token lifetimeHow long one access token is valid before the browser renews it15m1 minute to 24 hours. A duration such as 15m, 12h or 1h30m; a whole number of days such as 1d is also acceptedPlatform adminjwt_access_duration
JWT refresh token lifetimeHow long a session lasts without signing in again7d1 hour to 2160 hours (90 days). A duration such as 12h or 168h, or whole days such as 7dPlatform adminjwt_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 doesDefaultAllowed valuesWho can change itAPI 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 installed140 (none) to 90Platform adminlicense_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​

FieldShows
Modeonline or offline: how the license was activated
StatusValid or Invalid
PlanThe licensed plan
ExpiresThe expiry day, when the license has one
Last checkedWhen the license was last checked: the last answer of the license server for an online license
FingerprintThis installation's fingerprint
ReasonWhy 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:

ReasonWhyWhat to do
the license has not been checked with the license service yetAn online license has no signed answer from the license server yet, for example right after an upgrade while the server cannot be reachedSelect Check now once the license server can be reached, or activate the key again
the stored license check could not be verifiedThe stored license data does not match a signed answer for this license and installationActivate the license key again

Activating and removing​

Setting (label in the UI)What it doesWho 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 againPlatform admin
License key (card Online license)Activates a license online with ActivatePlatform admin
License file (card Offline license)Upload license file activates a signed offline license file (.json), for environments without internet accessPlatform admin
Remove licenseRemoves the active license after a confirmation. Webhook processing stops until a new license is activatedPlatform admin

A key or file that is refused leaves the current license as it was. The message says why:

MessageWhyWhat to do
the license was refused: license key not found (or license expired, license is not active)The license server does not accept the keyCheck 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 instancesDeactivate it on an instance that no longer needs it, or ask for more activations
set the license API key first, then activate the license keyOnline activation needs the license API keySave the key on the API key card first
the license service could not be reached; try again later, or activate with an offline license fileThe license server did not answer, answered with an error of its own, or sent an answer that is not signed with CloudNativeWorks' keyTry 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 changedUpload the file exactly as you received it
the license file expired on YYYY-MM-DD: ask for a renewed license fileThe offline license file has expiredAsk for a renewed file

License actions are recorded in the audit log as set_license_api_key, activate_license, check_license and deactivate_license.