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
| Action | Who |
|---|---|
| See the Companies page, create a company, deactivate a company | Platform admins, from a signed-in session (API tokens are refused) |
| Turn a company off or on with the Active switch of its General tab | Platform admins only |
| Open the company page and change the company's settings | Company admins of that company, and platform admins |
| Read the company's settings through the API | Every 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.
| Column | Shows |
|---|---|
| Name | The company's name |
| Slug | The short name in the company's webhook URLs |
| Description | The description, or - when there is none |
| Status | Active 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Name | The company's name | none, required (Enter a name) | Any text | Platform admin | name |
| Slug | Not 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 name | Read-only | Nobody | slug |
| Description | A note shown in the list and on the company page | Empty | Any text | Platform admin | description |
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
Header
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.
| Step | Done when | Link |
|---|---|---|
| Set the Application URL | The 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 GitLab | The company has a VCS connection | Open Connections. See Connections |
| Link a tracker to the connection | A 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 policy | The 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 management | The 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 channel | The 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
| Tab | What it holds | Documented on |
|---|---|---|
| General | Name, description, time zone, whether the company is active, the branch patterns | General |
| Connections | The company's VCS and tracker connections and the default of each kind | Connections |
| Repositories | How repositories are watched and added, and what is done about direct changes | Repository settings |
| Notifications | What is announced, notification routes, the mail server and the delivery log | Notifications |
| Sign-in | How the company's people sign in: passwords, the company directory, identity providers, GitLab and GitHub | Sign-in |
| Approvals | How change approvals are decided: tracker approvals, emergencies, unassigned change approvals, stand-ins, approval fatigue, approver pools | Approvals |
| People | How a person is found in the tracker, who creates change approvals, and a check of every person | People |
| Change calendar | Change windows and change freezes | Change calendar |
| Risk | Risk assessment and how risk is scored | Risk |
| Scanning | Company defaults of the secret scan, dependency scan, licenses, package health, workflow and signature checks, and the vulnerability inventory | Scanning |
| API tokens | Service tokens, and whether people may make personal tokens | API tokens |
| Governance | Four-eyes review of control changes, and how long the audit log is kept | Governance |
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.
| Settings | Reviewed as |
|---|---|
| Risk tab, change windows and change freezes | Risk settings and change freezes |
| Sign-in tab, except identity providers | How people sign in |
| The company directory (LDAP) | The company directory (LDAP) |
| Let people make personal API tokens | Whether people may make personal API tokens |
| Turning Review control changes off | Switching 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.
| Request | Who | What it does |
|---|---|---|
GET /companies | Signed in | Platform 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 company | The company's settings. Secrets are never returned: has_password, has_bind_password, has_webhook_url and has_secret say whether one is stored |
POST /companies | Platform admins, signed-in session | Creates 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 admins | Changes 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 session | Deactivates 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
| Action | When |
|---|---|
create_company | A company was created (with its name and slug) |
update_company | The 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_company | A company was deactivated. Can be a failure |
config_change_requested, config_change_approved, config_change_rejected | With four-eyes review on: a change was sent for review, approved or rejected (see Governance) |
See Audit log.
Related pages
- 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 →