Why GitLab Admin Mode matters for administrator access
Admin Mode makes a GitLab administrator confirm their identity again before performing administrative actions, such as changing instance settings, managing users or opening the Admin area. Teams need it when more than one person can reach that area, or when a single unattended session could change sign-in rules, runner access or visibility for every project on the instance. On a self-managed instance, administrators hold broad reach over users, runners and settings, so a session left open at a shared or unattended workstation is a serious exposure. Admin Mode narrows that window, but it is one control among several and does not replace the others.
Admin Mode works alongside the number of full administrators, two-factor authentication for administrator accounts and custom admin roles, each of which is covered in later sections of this page. Its exact behavior depends on the GitLab version you run, including how it is enabled, which actions it covers and how long a confirmation remains valid. Confirm these details in the GitLab authentication and authorization documentation for your version, and check how re-authentication behaves for users who sign in through an external identity provider before you write a policy around it.
Before you change anything, list every account with administrator rights and ask why each one needs them. Then test Admin Mode on a non-production instance that runs the same GitLab version and identity provider as production. Observe which prompts your administrators will meet, and check whether scripts or API tasks that run under administrator accounts are affected. Record the results, because the same findings will shape the access model, the approval steps and the evidence you collect later.
Admin access options and when each fits
This table compares four ways to control administrator access on self-managed GitLab: Admin Mode, administrator 2FA, custom admin roles and a break-glass account. Read each row for the risk it addresses, the instance type it suits and the friction it adds for administrators. Most instances benefit from the first two controls, while the last two depend on size, tier and how many people need admin rights.
| Option | Risk it addresses | Best fit and operator friction |
|---|---|---|
| Admin Mode | A stolen or unattended session performing administrative changes without a fresh login | Small single-team instances gain a cheap guard with little friction. Regulated multi-team instances should require it for everyone with admin rights, and administrators must re-authenticate for each privileged session. |
| Enforced 2FA for administrators | Password-only administrator accounts being compromised through phishing or credential reuse | Fits any instance with administrators. Friction is one enrollment per admin and a recovery process when a device is lost. Confirm the enforcement setting in your version's documentation. |
| Custom admin roles | Full administrator rights granted to people who only need narrow tasks such as user management or runner administration | Best for multi-team instances with distinct operator duties. Friction comes from designing and reviewing roles. Confirm in the pricing page whether custom admin roles are included in your tier before planning around them. |
| Break-glass administrator account | Lockout when SSO, LDAP or the identity provider fails, with no one able to fix the instance | Useful on regulated instances where identity is centralized. Friction comes from securing a rarely used account, storing its credentials under dual control and testing that it still works. Confirm how your edition handles it. |
| Keeping full administrators few | Broad, standing privilege that multiplies the impact of any single compromise | Applies to every instance size. Friction is occasional requests for elevated access, which a documented approval step handles. Review the admin list on a set schedule. |
Setting up Admin Mode and administrator 2FA
This sequence moves a self-managed GitLab instance from broad, always-on administrator access to a smaller set of administrators who must re-authenticate for administrative actions and use two-factor authentication. Each step ends with a check you can repeat after the change.
Inventory current administrators and their access
Before changing anything, list every user with full administrator access on the instance, including service accounts, shared logins and accounts tied to former staff. Use the Admin area user list to filter for administrators, then record each account's owner, purpose and last sign-in. Compare the list with your identity provider so you can see which accounts map to real people. The step is done when you have a reviewed list signed off by the operations owner, with each account marked as keep, convert to a custom role or remove.
Enable Admin Mode for administrative actions
In the Admin area settings, turn on Admin Mode so that administrators must re-authenticate before they perform sensitive actions. Confirm the exact setting path and behavior against the GitLab authentication documentation for your version, because the menu location can change between releases. Make the change in the maintenance window agreed with your operations team, and tell administrators in advance that they will be prompted. The check: sign in as a test administrator, open an administrative page, attempt an administrative action, and confirm that GitLab asks for re-authentication before it proceeds.
Require two-factor authentication for administrators
Enable the instance-level requirement that administrators have two-factor authentication configured before they can use administrative functions. Ask each administrator to register a second factor before the requirement takes effect, and plan for a short period when accounts without 2FA are blocked. Confirm the current option name and enforcement behavior in the GitLab authentication documentation, since enforcement rules differ between sign-in methods such as LDAP, SAML or local passwords. The check: sign in with a test administrator account that has no second factor and confirm access is blocked, then sign in with an account that has one and confirm it works.
Create or review custom admin roles
Identify the tasks that administrators currently perform, such as user management, runner administration or monitoring, and map them to the narrowest custom admin roles your GitLab edition supports. Custom admin roles are a capability to confirm for your tier and version, so check the pricing page and feature documentation before designing around them. Assign roles to a pilot group first and record which permissions each person needs. The check: sign in as a test user with the new role, attempt the tasks it should allow and the tasks it should not, and confirm that the results match the role design.
Remove unnecessary full administrators
Reassign or remove full administrator rights from accounts that the inventory marked as unnecessary, moving their work to custom roles where possible. Keep at least one named, accountable break-glass administrator documented in your runbook, and store its recovery credentials under your normal secrets controls. Remove access in the same maintenance window so the change is visible in one place to the operations team. The check: re-run the administrator list, confirm it matches the approved inventory, and confirm each removed account can no longer reach the Admin area.
Verify each change and record the evidence
Test the full configuration as a set rather than trusting each earlier check in isolation. Repeat the re-authentication test, the 2FA block test, the custom role tests and the administrator count, then save the results with dates, account names and settings screenshots or exported values. Store the record with your change management evidence so an auditor or internal reviewer can trace each control. The step is complete when every check passes, any exceptions have a named owner, and the operations team has accepted the record.
Security and operational considerations for administrator access
Admin Mode and two-factor authentication protect a single administrative session, but the wider risk sits in who holds administrator rights, how those accounts recover, and whether anyone reviews what they do. The cards below cover the controls that keep administrator access small, recoverable and visible over time.
Protect break-glass accounts
A break-glass account is a reserved administrator that works when identity provider sign-in, SSO or the normal admin team is unavailable. It is a common target because it is rarely used and often poorly watched. Keep its credentials offline in sealed custody, store its 2FA recovery material separately, and test that it can still sign in on a planned schedule. Confirm with your identity team whether this account should bypass SSO at all, since that decision changes how it is monitored.
Secure the 2FA recovery path
Lost or replaced 2FA devices are a frequent reason administrators are locked out, and a weak recovery process can become the easiest way in. Define in advance who can reset another administrator's second factor, how that person's identity is verified, and where the request is recorded. Ask for the exact reset steps in your GitLab version and confirm that a reset by one administrator is logged and reviewed by a second person.
Log and review administrator actions
Administrative changes such as user role edits, sign-up settings, runner registration and project visibility changes are where misuse shows up. Route GitLab audit events and your instance logs to a central store that administrators cannot edit, and set a recurring review of changes made in administrator sessions. Confirm which administrative actions produce audit events in your edition, because coverage differs and some events are tier dependent.
Keep service accounts out of admin roles
Integrations, bots and CI automation often run under accounts created with full administrator rights because it was the quickest way to make them work. A compromised token then grants instance-wide control. Give service accounts the narrowest role that completes their task, use project or group access tokens where possible, and use custom admin roles for the few administrative permissions they truly need. Check the account list for bots with admin status.
Review the administrator list on a schedule
Administrator rights accumulate as people change teams, and departed staff or temporary contractors often keep them. Set a fixed review cadence, compare the list of full administrators against your current staffing and change records, and remove rights that are no longer needed. Record each review and its outcome so the result can be shown to auditors. Ask your team how the review is sourced, whether from an identity export, a directory group or a manual check.
Align host and configuration hardening
Admin Mode controls the application, but the server and configuration files define what an attacker can reach. GitLab's hardening guidance covers the operating system and the gitlab.rb configuration file, and it notes the guidance is a work in progress to be rolled out gradually. Restrict root and SSH access to the host, protect the file that holds secrets, and track each setting you adopt. Confirm current recommendations against the hardening page for your installed version before changing production.
Keeping the number of full administrators small
Keep the list of full administrators short, because every account with full administrator rights can change instance-wide settings, read or alter any project, and grant access to others. A small group makes it realistic to review who holds that power, to enforce two-factor authentication and Admin Mode for each of them, and to investigate quickly when an account is compromised. Before granting access, list the administrative duties your teams actually perform, such as creating users, managing groups, administering runners or reviewing audit events, and decide which of those belong to a person who needs everything. Most duties do not.
Custom admin roles are the GitLab mechanism for delegating narrower work, such as user management or runner administration, without handing out full administrator rights. The trade-off is that each role is one more thing to design, test, document and audit. Map every delegated duty to a specific role before granting it, and write down which permissions that role includes. Do not assume the permission names or their scope from memory or from another version. Confirm the custom role permissions available in the GitLab version you run against the GitLab authentication and authorization documentation, and check them again at each upgrade stop, since the set of delegable permissions can change between releases.
Review the assignments on a fixed schedule, and remove roles when a responsibility moves or a person leaves. For each role, record the duty, the permissions granted, the named holders and the reviewer who approved the grant. Test the role in a non-production instance by signing in as a holder and attempting both the permitted actions and the ones that should fail. Illustrative example: a runner administrator who can register and pause runners should be refused when trying to change instance sign-up settings. If the test shows a role can do more than its duty requires, narrow it before it reaches production.
Limits to confirm in your environment
Admin Mode, two-factor enforcement, custom roles, recovery and audit logging interact with your identity provider, your GitLab version and your operating model. Confirm each item against the vendor documentation or a test instance before you write it into an access standard.
Which actions Admin Mode covers
Confirm which administrative actions require re-authentication in your version, and which sit outside Admin Mode. Check whether project-level and group-level owner actions are covered, and whether API calls made with administrator personal access tokens are treated the same way as browser sessions. Test each action on a non-production instance and record the results, since coverage can change between releases.
2FA enforcement with your identity provider
Ask how two-factor enforcement behaves when administrators sign in through SAML, LDAP, OAuth 2.0 or another OmniAuth provider. Determine whether GitLab enforces a second factor on top of the provider's own MFA, or whether it relies on the provider. Confirm what happens to service accounts and break-glass accounts that do not use the same sign-in path.
Custom roles against real duties
List the duties your platform team needs, such as managing runners, users or groups, and check whether custom admin roles can separate them without granting full administrator rights. Confirm which permissions each custom role includes in your tier, because some capabilities may still require a full administrator. Document any duty that can only be performed by a full administrator, since that account becomes the highest-risk path.
Recovery for locked-out administrators
Determine how an administrator recovers access after losing a second factor, a identity provider outage or a misconfigured Admin Mode policy. Confirm whether a console-based reset, a second administrator or a recovery code process is documented for your version. Write the procedure down, test it on a non-production instance, and confirm who holds the credentials for the emergency path.
Audit log retention and export
Confirm how long administrative events remain in the instance, which events are recorded for Admin Mode and role changes, and whether logs can be exported to your SIEM. Check whether retention depends on your tier, and whether logs capture the actor, the action and the time with enough detail for an investigation. Ask whether logs can be shipped off the instance before they are rotated.
Questions teams ask before changing administrator access
What does it cost to configure Admin Mode and 2FA internally versus with a partner?
Internal cost is mostly staff time, and partner cost follows from a written scope, so neither figure can be known until the instance count and identity setup are documented. The main cost drivers are the number of GitLab instances and how many people hold administrator rights, the complexity of your identity provider (for example, whether administrator sign-in runs through SAML, LDAP or a combination), and how much testing is needed before the change reaches production. Recurring cost is small and mostly review: each new administrator, role change or identity provider update needs someone to check the settings still hold. Ask any partner for a quote that lists the instances in scope, the identity sources, the test environment and the handover documentation as separate line items.
How long does a review of administrator access take?
The duration depends on the number of administrators, the instances involved and whether the identity provider already enforces multi-factor sign-in. A review of a single instance with a short administrator list is much shorter than a review spanning several instances with custom admin roles and external identity sources. The work breaks into four stages: inventory of current administrators and their roles, a test on a non-production instance to confirm Admin Mode prompts and 2FA behave as expected, a change window for production, and a post-change check. Ask for a timeline in the written scope that names each stage, so you can see where delays would come from.
What must our team provide before administrator access is reviewed?
Start with four inputs that the work depends on:
- A current list of every user with administrator rights, including service accounts and any users with custom admin roles.
- Access to your identity provider, or a named contact who can change its settings, so that sign-in and multi-factor rules can be checked against GitLab.
- A test instance that matches production closely enough to rehearse Admin Mode and 2FA enforcement, including the same authentication providers.
- A change window agreed with the teams who depend on GitLab, because enforcing 2FA can lock out users who have not yet enrolled.
Also confirm who approves the final administrator list, since that decision belongs to your organization.
Can a small internal team change administrator access on its own?
Yes, a small team can usually handle the configuration if it has someone comfortable with GitLab administration and access to the identity provider. The settings for Admin Mode, administrator 2FA and custom admin roles are part of the instance administration area, so the risk lies less in clicking the wrong option and more in testing the change properly. The areas most often underestimated are the identity provider side, the test rehearsal and the documentation that lets the next administrator understand why the roles are set as they are. Decide before starting whether the internal team will own ongoing reviews, and whether a partner will cover only the design and test, the rollout or both.
How do we recover if an administrator is locked out after enforcing 2FA?
Plan the recovery path before the change, not after. Keep at least one other administrator who has already enrolled in two-factor authentication and confirmed they can complete Admin Mode re-authentication. Make sure someone with root access to the server can reach the GitLab command line, because that access lets an operator reset or adjust a user's sign-in settings from the host. Test the recovery steps on the test instance so the procedure has been rehearsed. Record the steps in your runbook and confirm them with your GitLab support or implementation provider, since exact commands depend on your installation method and version.
Does enforcing 2FA and Admin Mode satisfy an audit requirement by itself?
No. Enabling Admin Mode and 2FA for administrators reduces the chance that a stolen session or unattended browser is used for administrative actions, but it does not establish compliance on its own. Auditors look for evidence: the administrator list, who approved each role, when settings changed, and how access is reviewed over time. Preparing that evidence is part of the work, and it is the organization's responsibility to decide which controls apply to its environment. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or attestation. Confirm the exact control expectations with your assessor before the change.
Should we keep several full administrators or use custom admin roles instead?
Keep the number of full administrators small and give most staff narrower custom admin roles where GitLab supports them. A full administrator can change nearly every instance setting, so each extra full administrator widens the impact of a compromised account. Before deciding, list the tasks each person performs, such as user management, runner administration or audit log review, and check which custom roles cover those tasks in your GitLab edition and version. Confirm the available role permissions against the current GitLab documentation, because role capabilities change between releases.
Which GitLab edition do we need for administrator access controls?
Confirm this against the current GitLab pricing page before planning, because feature availability by tier can change. The pricing page lists GitLab Free, Premium and Ultimate as available for self-managed installations, and it places compliance features under Ultimate. Admin Mode and 2FA enforcement should be checked against the tier you run, and custom admin roles may depend on your edition as well. Ask your implementation partner or GitLab sales to confirm which controls your current tier includes before you commit to a design that assumes them.
How DeployOpen scopes administrator access work on GitLab
DeployOpen scopes administrator access work on GitLab as a fixed-scope engagement, with the scope, deliverables and timeline agreed in writing before any change is made to your instance. The starting point is a review of who currently holds administrator rights, which accounts are full administrators, which are service or shared accounts, and whether Admin Mode and two-factor authentication are enforced for them. The review produces a written inventory of administrator accounts and roles, with each gap tied to a specific setting, such as whether Admin Mode is turned on in the Admin Area, whether administrators must use two-factor authentication, and whether any custom admin roles already exist. Your team confirms the findings against its own access records before any remediation is proposed.
Changes are then tested on a non-production GitLab instance where you provide one, so that enabling Admin Mode, changing role assignments or adjusting sign-in requirements can be checked against your real CI/CD jobs, service integrations and break-glass procedures before they reach production. If no non-production instance exists, DeployOpen will say so in the scope and agree how changes will be staged and rolled back. The handover includes the configuration record, the role and permission matrix, the steps for granting and removing administrator access, and runbooks for recovering locked-out administrators. Your team should confirm the exact deliverables, their format and who maintains them after handover.
DeployOpen prepares controls, configuration records and evidence that support compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations. Because administrator access drifts as people join, move and leave, many organizations choose a retainer for periodic access reviews, configuration checks after GitLab upgrades and updates to runbooks. Retainer scope and frequency are agreed in writing, and you should ask for them to be stated separately from the one-time implementation scope in any quote.
