Skip to main content
Video tutorial · 1:17

Companies

A company is a tenant of Merge Pilot: its own connections, projects, change policies, people and settings, kept apart from every other company on the same instance (see Core concepts). Each person belongs to one company and has a role in it; platform admins belong to none and work with every company.

This page covers creating and deactivating companies, choosing which company you work in, and the company page where a company's settings live.

Who may do what​

ActionWho
See the Companies page, create a company, deactivate a companyPlatform admins, from a signed-in session (API tokens are refused)
Turn a company off or on with the Active switch of its General tabPlatform admins only
Open the company page and change the company's settingsCompany admins of that company, and platform admins
Read the company's settings through the APIEvery role of that company, and platform admins

Platform admins reach a company page from the Companies page. A company admin has no Companies page; the sidebar shows Company under Administration, which opens their own company.

The Companies page​

Administration → Companies. It lists every company, active or not, sorted by name, a page at a time.

  • Search by name or slug: matches part of the name or the slug, ignoring case.
  • Add company: opens Create company.
  • Select a row (or the name) to open the company page.
ColumnShows
NameThe company's name
SlugThe short name in the company's webhook URLs
DescriptionThe description, or - when there is none
StatusActive or Inactive

Each row has two buttons:

  • Edit (pencil): opens Edit company to change the name and the description.
  • Deactivate (bin): asks Deactivate company, "… will be deactivated. All webhooks and processing for this company stop.", and deactivates it on Deactivate. The company is not removed: it stays in the list as Inactive, keeps all its data, and is turned back on with the Active switch on its General tab.

Create company​

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
NameThe company's namenone, required (Enter a name)Any textPlatform adminname
SlugNot entered: Made from the name when the company is created; it is part of the company's webhook URLs, so it does not change. The name is put in lower case and every run of characters other than a–z and 0–9 becomes a hyphen (Acme Payments → acme-payments)From the nameRead-onlyNobodyslug
DescriptionA note shown in the list and on the company pageEmptyAny textPlatform admindescription

Two companies cannot have the same slug: a name that gives a slug already in use is refused (company with slug "…" already exists). A name with no letter or digit is refused too (400), since its slug would be empty.

A new company starts active, with the branch patterns set to Repository default branch, review of control changes off, risk assessment off and repositories added in watching mode. Everything else is set on the company page; the setup checklist shows what to do first.

Deactivating a company​

While a company is inactive:

  • the webhooks of its VCS and tracker connections are answered but ignored;
  • its people cannot sign in, and their sessions end;
  • its API tokens are refused (they are not revoked, and work again when the company is active again);
  • it is left out of the company selector in the header and out of the companies the sign-in page offers.

Only platform admins turn a company off or on: for company admins the Active switch on the General tab is disabled (Only platform admins turn a company off or on.), and the API answers 403 when they turn it off.

The branch head check and the vulnerability advisory check do not run for an inactive company; its old direct-change records are still removed and its vulnerability exceptions still expire.

The company selector​

The header has a company selector (Select company). The pages of the app show the data of the selected company.

  • Platform admins choose among all active companies. Everyone else sees only their own company.
  • The choice is remembered in the browser.
  • Switching while a detail page is open (a merge request, a project, a tracker issue or a company page) goes back to that page's list first. When the company page has unsaved changes, Merge Pilot first asks Leave without saving?; staying keeps the current company.

The company page​

The company's name, its slug below it, and a Change policies button that opens the company's change policies. Platform admins also get a back arrow and a Back to companies button.

Set up this company​

A checklist at the top walks a new company's administrator through what Merge Pilot needs before it governs anything: such as "2 of 6 done. Merge Pilot governs changes once these are in place." Each step that is not done links to where it is done.

StepDone whenLink
Set the Application URLThe platform's Application URL is set (The VCS and tracker send webhooks to it.)Open platform settings for platform admins; others read Ask a platform administrator to set it. See Platform settings
Connect GitHub or GitLabThe company has a VCS connectionOpen Connections. See Connections
Link a tracker to the connectionA VCS connection of the company has a linked tracker connection (Normal and emergency changes need a change approval in a tracker (the built-in one works).)Open Connections. See Permissions and tracker link
Add a change policyThe company has a policy other than a catch-all that refuses everything (Until then the catch-all refuses every change.)Open change policies. See The catch-all of a new connection
Watch a repository or put it under change managementThe company has at least one project (Start by watching one: nothing is written to it until you move it to change management.)Open projects. See Watching
Turn on a notification channelThe company has an active notification route (So people hear about changes waiting for them.)Open Notifications (the Notifications tab)

The checklist disappears once every step is done. Hide hides it for good for everyone in the company (setup_dismissed: true); it can be shown again only through the API (setup_dismissed: false).

API: GET /api/v1/companies/{id}/setup-status (company admins, platform admins) answers steps (each with key and done, in the order above: app_url, vcs_connection, tracker_linked, policy, repository, notifications) and dismissed.

Tabs​

TabWhat it holdsDocumented on
GeneralName, description, time zone, whether the company is active, the branch patternsGeneral
ConnectionsThe company's VCS and tracker connections and the default of each kindConnections
RepositoriesHow repositories are watched and added, and what is done about direct changesRepository settings
NotificationsWhat is announced, notification routes, the mail server and the delivery logNotifications
Sign-inHow the company's people sign in: passwords, the company directory, identity providers, GitLab and GitHubSign-in
ApprovalsHow change approvals are decided: tracker approvals, emergencies, unassigned change approvals, stand-ins, approval fatigue, approver poolsApprovals
PeopleHow a person is found in the tracker, who creates change approvals, and a check of every personPeople
Change calendarChange windows and change freezesChange calendar
RiskRisk assessment and how risk is scoredRisk
ScanningCompany defaults of the secret scan, dependency scan, licenses, package health, workflow and signature checks, and the vulnerability inventoryScanning
API tokensService tokens, and whether people may make personal tokensAPI tokens
GovernanceFour-eyes review of control changes, and how long the audit log is keptGovernance

A tab with unsaved changes carries a dot.

Saving​

The settings on the tabs form one page and are saved together. As soon as something changes, a bar appears at the bottom: You have unsaved changes., with Discard (back to the saved values) and Save changes.

  • Saving checks every tab. When a field on another tab is wrong, that tab opens and shows the error.
  • Change windows and change freezes must each have a name: Name every change freeze and change window you filled in, or remove it.
  • Success shows Changes saved.
  • Leaving the page with unsaved changes asks Leave without saving? (Your changes to this company's settings have not been saved and will be lost.), with Leave without saving. Closing or reloading the browser tab warns too.

Lists with their own buttons and dialogs are saved by those, not by Save changes: connections and the default connections, identity providers, approver pools, API tokens and stand-ins, and the Hide button of the setup checklist.

Some saves start work in the background: changing the branch patterns (or whether push events are received) updates the webhook of every registered repository of the company (the events_sync job, see Jobs).

Four-eyes review on the company page​

When the company has turned on Review control changes (Governance), some settings on this page do not take effect when saved:

  • the bar says which, before saving: Goes to a second administrator: … followed by the topics (such as Risk settings and change freezes);
  • Save changes saves everything else and sends the reviewed parts for review: Saved. Sent for review: … with the summaries of the changes as written, separated by semicolons;
  • the page then shows the saved values, so a reviewed setting appears unchanged until it is approved.
SettingsReviewed as
Risk tab, change windows and change freezesRisk settings and change freezes
Sign-in tab, except identity providersHow people sign in
The company directory (LDAP)The company directory (LDAP)
Let people make personal API tokensWhether people may make personal API tokens
Turning Review control changes offSwitching this review off

A setting saved with the value it already has is not sent for review. The changes waiting for review from this page (and approver pool changes) are listed in a box above the tabs, where another administrator approves or rejects them. Identity providers have their own box on the Sign-in tab, and change policies on the Change policies page. See Governance.

Company API​

All paths start with /api/v1.

RequestWhoWhat it does
GET /companiesSigned inPlatform admins: every company, sorted by name, with q (search in name and slug), active=true (only active companies), page and page_size (default 20, at most 100). Everyone else: a list with only their own company
GET /companies/{id}Platform admins; others for their own companyThe company's settings. Secrets are never returned: has_password, has_bind_password, has_webhook_url and has_secret say whether one is stored
POST /companiesPlatform admins, signed-in sessionCreates a company. Takes name (required), description, branch_patterns, notifications and ldap. 201 with the company; 400 when the name has no letter or digit; 409 when the slug is taken
PUT /companies/{id}Company admins of that company, platform adminsChanges the fields sent and leaves the others alone. 200 with the company; 400 when a value is not allowed (such as a blank name, an unknown time zone or empty branch patterns); 403 when someone other than a platform admin sets active: false. With four-eyes review on and a reviewed part changed: 202 Accepted with {"company": {…}, "pending": [ … ]}, the waiting changes
DELETE /companies/{id}Platform admins, signed-in sessionDeactivates the company (active: false); nothing is removed. 204

A request made with an API token cannot change sign_in, ldap, smtp, governance, personal_api_tokens or audit_retention_days: it is refused with 403 (API tokens cannot change …: use a signed-in session). See API tokens.

The fields of each tab are listed on the tab's page.

Audit log​

ActionWhen
create_companyA company was created (with its name and slug)
update_companyThe company's settings were saved, with what changed; also when the setup checklist is hidden, and when a reviewed change is approved and applied (written by the approver, naming who requested it). Can be a failure
delete_companyA company was deactivated. Can be a failure
config_change_requested, config_change_approved, config_change_rejectedWith four-eyes review on: a change was sent for review, approved or rejected (see Governance)

See Audit log.

  • General: the company's name, time zone, status and branch patterns.
  • Governance: four-eyes review of control changes.
  • Roles and users: the roles and the Users page.
  • Connections: connecting GitLab, GitHub and a tracker.

Video tutorial

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 ↗