<details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=585040) </details> ### 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:** ```yaml 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: ```bash 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 - Documentation: [Merge Request Approval Policies - Bypass Settings](https://docs.gitlab.com/ee/user/application_security/policies/merge_request_approval_policies.html#bypass-merge-request-approval-policy-in-emergency-situations) - #587530 (closed as duplicate) - Reports that `approval_settings` are not bypassed when `bypass_settings` is used ### 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