Allow Merge Approval Policy bypass_settings to override protected branch push restrictions

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem to Solve

Currently, the bypass_settings parameter in Merge Request Approval Policies only bypasses push protection enforced by the security policy itself (via prevent_pushing_and_force_pushing: true), but cannot bypass:

  1. Restrictions configured at the protected branch level (e.g., "Allowed to push and merge" set to "No One")
  2. Approval requirements configured in approval_settings (e.g., approvals_required, prevent_approval_by_author, etc.)

This limitation prevents organizations from implementing a unified bypass mechanism for emergency scenarios, even when they have explicitly configured authorized users, groups, roles, or access tokens in the bypass_settings section of their approval policy.

Current Behavior

When a protected branch has strict push protection configured (e.g., "Allowed to push and merge" = "No One") and approval settings are enforced:

  1. Users/tokens listed in bypass_settings can successfully bypass the security policy's push protection when using git push -o security_policy.bypass_reason="reason"
  2. However, the push is still blocked by the protected branch's own push restrictions
  3. The bypass only works if the protected branch settings independently allow the user/token to push

This creates a confusing user experience where bypass_settings appears to be partially functional.

Proposed Solution

Extend the bypass_settings functionality to override all policy-enforced restrictions:

  • Security policy push protection (prevent_pushing_and_force_pushing)
  • Protected branch push restrictions
  • Approval requirements from approval_settings (e.g., approvals_required, prevent_approval_by_author, prevent_approval_by_commit_author, remove_approvals_with_new_commit, require_password_to_approve)

When a user, group, role, or access token is listed in bypass_settings and provides a valid security_policy.bypass_reason, they should be able to:

  • Push directly to the protected branch regardless of the branch's "Allowed to push and merge" configuration
  • Have merge requests exempted from all approval_settings overrides

Implementation Considerations

Security Safeguards:

  • This behavior could be controlled by an opt-in setting in the approval policy (e.g., allow_comprehensive_bypass: true) to prevent unintended security relaxation
  • Bypass events should continue to be logged as audit events in the security policy project
  • The bypass reason should be mandatory and logged for accountability

Alternative Approach: If an opt-in setting is not desired, the current behavior could be maintained as the default, with clear documentation explaining the limitation and recommending that protected branch settings be configured to allow pushes from authorized bypass users/tokens.

Use Cases

  1. Emergency Hotfixes: During critical incidents, authorized users need to bypass all protections (policy, branch level, and approval requirements) to deploy urgent fixes
  2. Automated Deployments: Service accounts and access tokens configured in bypass_settings need to push directly to protected branches as part of automated release workflows
  3. Compliance with Flexibility: Organizations want strict default protections but need a controlled, audited bypass mechanism for exceptional circumstances

Expected Behavior

Example Configuration:

approval_policy:
  - name: Strict Approval Policy
    enabled: true
    rules:
      - type: any_merge_request
        branch_type: protected
    actions:
      - type: require_approval
        approvals_required: 2
    approval_settings:
      prevent_pushing_and_force_pushing: true
      prevent_approval_by_author: true
      remove_approvals_with_new_commit: true
    bypass_settings:
      users:
        - id: 123
      access_tokens:
        - id: 456

Protected Branch Configuration:

  • Branch: main
  • Allowed to push and merge: "No One"

Expected Result: When user 123 or access token 456 executes:

git push -o security_policy.bypass_reason="Emergency hotfix for incident #789"

The push should succeed, bypassing:

  • The approval policy's push protection
  • The protected branch restriction
  • All approval_settings requirements (approvals, author restrictions, etc.)

The bypass event should be logged in the audit log.

Documentation

The current documentation states:

The security_policy.bypass_reason push option works only for branches with push protection from a merge request approval policy configured with approval_settings. Pushes to protected branches that are not covered by a merge request approval policy cannot be bypassed with this option.

This should be updated to clarify:

  • Whether bypass_settings can override protected branch restrictions (if this feature is implemented)
  • Whether bypass_settings exempts merge requests from approval_settings overrides
  • The interaction between security policy bypass and protected branch settings
  • Best practices for configuring both mechanisms together

Related Issues/MRs

Proposal

Preferred Option: Add an opt-in setting allow_comprehensive_bypass to the approval policy configuration that, when enabled, allows bypass_settings to override all policy-enforced restrictions including protected branch push restrictions and approval settings.

Alternative Option: Change the default behavior to allow comprehensive bypass when bypass_settings is configured, with clear audit logging and documentation of the security implications.

Related to internal discussion: https://gitlab.com/gitlab-com/request-for-help/-/issues/3975

Edited by Dominic Bauer