Skip to content

feat: Add bypass allowlist for branch protection - #36514

Merged
bircni merged 38 commits into
go-gitea:mainfrom
bircni:feature/bypass-branch-protection-allowlist
May 16, 2026
Merged

bircni merged 38 commits into
go-gitea:mainfrom
bircni:feature/bypass-branch-protection-allowlist

Conversation

@bircni

@bircni bircni commented Feb 1, 2026 •

Copy link
Copy Markdown
Member
  • Introduce a “Bypass Protection Allowlist” on branch rules (users/teams) alongside admins, with BlockAdminMergeOverride
    still respected.
    • Surface the allowlist in API (create/edit options, structs) and settings UI; merge box now shows the red button +
      message for bypass-capable users.
    • Apply bypass logic to merge checks and pre-receive so allowlisted users can override unmet approvals/status checks/
      protected files when force-merging.
    • Add migration for new columns, locale strings, and unit tests (bypass helper; queue test tweak).
image

Fixes #36476

@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Feb 1, 2026
@bircni
bircni force-pushed the feature/bypass-branch-protection-allowlist branch from 03c404c to 36d1fbf Compare February 1, 2026 16:32
@silverwind
silverwind requested a review from Copilot February 12, 2026 10:51

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request introduces a "Bypass Protection Allowlist" feature for branch protection rules, allowing specific users and teams to bypass branch protection checks (required approvals, status checks, and protected files) without requiring full administrator privileges. This addresses the need for "Merge Masters" or "Technical Leads" who need bypass capabilities while following the Principle of Least Privilege.

Changes:

  • Added database columns EnableBypassAllowlist, BypassAllowlistUserIDs, and BypassAllowlistTeamIDs to the ProtectedBranch model with migration v326
  • Implemented CanBypassBranchProtection helper function that checks both admin privileges and allowlist membership
  • Extended API endpoints and Swagger documentation to support bypass allowlist configuration
  • Updated branch protection settings UI to allow configuration of bypass users and teams
  • Modified pull request merge box to display appropriate messages for bypass-capable users
  • Applied bypass logic in pre-receive hooks and merge checks to allow allowlisted users to override unmet requirements

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
models/migrations/v1_26/v326.go Migration adding three new columns to ProtectedBranch table for bypass allowlist feature
models/migrations/migrations.go Registers the new migration v326
models/git/protected_branch.go Adds bypass allowlist fields to ProtectedBranch model and implements CanBypassBranchProtection function
models/git/protected_branch_test.go Unit tests for CanBypassBranchProtection covering various scenarios
modules/structs/repo_branch.go Extends API structs (BranchProtection, CreateBranchProtectionOption, EditBranchProtectionOption) with bypass allowlist fields
routers/api/v1/repo/branch.go Updates API endpoints to handle bypass allowlist users and teams during branch protection creation and editing
routers/web/repo/setting/protected_branch.go Handles bypass allowlist data in web UI forms for branch protection settings
routers/web/repo/issue_view.go Sets template data for bypass permissions to control merge button visibility and messages
routers/private/hook_pre_receive.go Applies bypass logic in pre-receive hook to allow bypass users to push despite protection checks
services/pull/check.go Uses CanBypassBranchProtection in merge checks instead of admin-only check, updates comment
services/pull/check_test.go Removes redundant queue.Has() checks that could cause test flakiness
services/forms/repo_form.go Adds bypass allowlist fields to ProtectBranchForm
services/convert/convert.go Converts bypass allowlist IDs to usernames/team names for API responses
templates/repo/settings/protected_branch.tmpl UI form for configuring bypass allowlist users and teams
templates/repo/issue/view_content/pull_merge_box.tmpl Displays context-appropriate message when bypass user can force merge
templates/swagger/v1_json.tmpl Swagger documentation for bypass allowlist fields in API
options/locale/locale_en-US.json Locale strings for bypass allowlist UI elements and messages

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread services/pull/check_test.go Resolved
Comment thread models/git/protected_branch_test.go Resolved
@bircni
bircni force-pushed the feature/bypass-branch-protection-allowlist branch from 36d1fbf to da1f775 Compare February 12, 2026 20:45
@silverwind

Copy link
Copy Markdown
Member

Review

I reviewed the full diff. The overall structure follows existing patterns well (model fields, migration, API plumbing, settings UI, template). A few observations:

1. Breaking behavior change in pre-receive hook

The original hook_pre_receive.go (line 371) unconditionally allows admins through:

if ctx.userPerm.IsAdmin() {
    return
}

The new code replaces this with CanBypassBranchProtection, which checks isRepoAdmin && !protectBranch.BlockAdminMergeOverride. This means admins who have BlockAdminMergeOverride enabled on a branch rule will now also be blocked in the git push (pre-receive) path, not just the web merge path. Previously those admins could always push past status checks, reviews, and protected files via direct push even with BlockAdminMergeOverride set.

This is arguably more correct behavior (closing an inconsistency), but it is a breaking change for existing setups and should be called out explicitly in the PR description and release notes.

2. Unrelated test change in check_test.go

The removal of prPatchCheckerQueue.Has(...) assertions and the reorder of go prPatchCheckerQueue.Run() is a test flakiness fix unrelated to the bypass allowlist feature. It should be in a separate commit (or separate PR) to keep the changeset focused.

3. Unused template variable IsBranchProtectionBypasser

In issue_view.go, IsBranchProtectionBypasser is computed and set in ctx.Data but is never referenced in any template. Either it should be used (perhaps to show a different UI indicator for bypass-list users vs admins), or it should be removed.

4. No integration test for the bypass merge path

The unit test for CanBypassBranchProtection is good, but there is no integration test covering the actual merge flow—e.g., a non-admin bypass-listed user force-merging a PR with failing status checks or missing approvals. Given this touches both the web merge check (CheckPullMergeable) and the pre-receive hook, an integration test would significantly increase confidence.

5. Minor: interaction between BlockAdminMergeOverride and bypass list

When BlockAdminMergeOverride is true, an admin who is also on the bypass allowlist can still bypass (because CanBypassBranchProtection falls through the admin check into the allowlist check). This is probably intentional, but it may surprise users who expect BlockAdminMergeOverride to block everyone. Worth a note in the UI help text or docs.


This comment was written by Claude (claude-opus-4-6) via Claude Code.

@silverwind

Copy link
Copy Markdown
Member

What do we do about point 1? Is it worth calling out a breaking change? I think not as it's probably too obscure of a feature.

@bircni

bircni commented Feb 26, 2026

Copy link
Copy Markdown
Member Author

I would not call it breaking but idk

@silverwind

Copy link
Copy Markdown
Member

Ok, please address points 3 and 4 if you can.

@bircni

bircni commented Feb 26, 2026

Copy link
Copy Markdown
Member Author

both are already done - I think

@silverwind
silverwind requested a review from Copilot February 26, 2026 18:47
@silverwind

Copy link
Copy Markdown
Member

any screenshot of the added ui?

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread routers/api/v1/repo/branch.go Resolved
Comment thread routers/api/v1/repo/branch.go Resolved
Comment thread models/git/protected_branch.go Resolved
Comment thread models/git/protected_branch.go Resolved
Comment thread models/git/protected_branch_test.go Resolved
@bircni

bircni commented Mar 3, 2026

Copy link
Copy Markdown
Member Author

fixed

@silverwind

Copy link
Copy Markdown
Member

Fix merge conflicts please and show a screenshot of the added UI.

@bircni
bircni force-pushed the feature/bypass-branch-protection-allowlist branch from 03d5b44 to b108b00 Compare March 13, 2026 20:29
@bircni

bircni commented Mar 13, 2026

Copy link
Copy Markdown
Member Author

@silverwind Done - here a screenshot
image

@bircni

bircni commented Mar 16, 2026

Copy link
Copy Markdown
Member Author

Updated so no conflicts

@bircni

bircni commented Mar 16, 2026

Copy link
Copy Markdown
Member Author

Also added a test which I somehow forgot back then :-(

@GiteaBot GiteaBot added lgtm/need 1 This PR needs approval from one additional maintainer to be merged. and removed lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. labels May 11, 2026
@bircni
bircni marked this pull request as ready for review May 11, 2026 14:17
@bircni bircni changed the title Add bypass allowlist for branch protection feat: Add bypass allowlist for branch protection May 11, 2026
bircni and others added 3 commits May 11, 2026 17:13
- Drop unused `cachegroup.BypassAllowlist` constant (cache path was
  already removed) and unused `repo.pulls.required_status_check_bypass_allowlist`
  locale key (no caller in this PR).
- Collapse `CanBypassBranchProtection` `(byAdmin, byAllowList bool)` return
  into a single `bool`; both callers discarded the first value, and the
  second was `true` even when only admin bypass applied.
- Guard the force-merge path against a nil protected-branch rule (race if
  the rule is deleted between `CheckPullBranchProtections` and the reload
  in the force-merge branch) and rename `adminForceMerge` -> `forceMerge`
  since the semantics now cover non-admin bypass users.
- Reshape the `EditBranchProtection` bypass user/team blocks to mirror
  the sibling allowlists (2-way `if name != nil { validate } else { keep }`)
  and clear both lists once at the end when the allowlist is disabled,
  instead of asymmetric per-block `else if !Enable` branches.

Co-Authored-By: Claude (Opus 4.7) <noreply@anthropic.com>

@silverwind silverwind left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cleanups done in ac1d0d0.

@GiteaBot GiteaBot added lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. and removed lgtm/need 1 This PR needs approval from one additional maintainer to be merged. labels May 13, 2026
@wxiaoguang

Copy link
Copy Markdown
Contributor

The prompt is missing?

image

@wxiaoguang
wxiaoguang marked this pull request as draft May 13, 2026 07:20
@bircni

bircni commented May 16, 2026

Copy link
Copy Markdown
Member Author

The prompt is missing?

Added it back

@bircni
bircni marked this pull request as ready for review May 16, 2026 13:39
@bircni
bircni enabled auto-merge (squash) May 16, 2026 13:56
@bircni
bircni merged commit eb93981 into go-gitea:main May 16, 2026
21 checks passed
@GiteaBot GiteaBot added this to the 1.27.0 milestone May 16, 2026
@bircni
bircni deleted the feature/bypass-branch-protection-allowlist branch May 16, 2026 14:24
silverwind added a commit to silverwind/gitea that referenced this pull request May 18, 2026
* origin/main: (39 commits)
  fix: Add missed token scope checking (go-gitea#37735)
  chore: Use giteabot instead of backporter (go-gitea#37422)
  fix: Allow direct commits for unprotected files with push restrictions (go-gitea#37657)
  chore: Conventional adjustments (go-gitea#37677)
  chore(db): introduce db.Session and db.EngineMigration interfaces (go-gitea#37746)
  fix(migrations): preserve unique constraints in v334 sync (go-gitea#37743)
  feat(web): also display PR counts in repo list (go-gitea#37739)
  feat: execute post run cleanup when workflow is cancelled (go-gitea#37275)
  fix(actions): wrong assumption that run id always >= job id (go-gitea#37737)
  fix(icon): use repo-forked icon to display forks count (go-gitea#37731)
  fix(oauth): strengthen PKCE validation and refresh token replay protection (go-gitea#37706)
  fix(web): enforce token scopes on raw, media, and attachment downloads (go-gitea#37698)
  feat: Add bypass allowlist for branch protection (go-gitea#36514)
  refactor(glob): use strings.Builder for regexp compilation (go-gitea#37730)
  feat(oauth): Support AWS Cognito OAuth2 provider (go-gitea#37607)
  feat: Add default PR branch update style setting (go-gitea#37410)
  refactor: move `workflowpattern` into `modules/actions` (go-gitea#37717)
  ci: add `zizmor` to `lint-actions` (go-gitea#37720)
  chore(doctor): remove four obsolete doctor check implementations (go-gitea#37728)
  chore(renovate): enable dockerfile manager (go-gitea#37719)
  ...

# Conflicts:
#	modules/globallock/locker_test.go
the-bets pushed a commit to the-bets/gitea that referenced this pull request Jun 10, 2026
zeekay pushed a commit to hanzoai/forge that referenced this pull request Jul 26, 2026
zeekay pushed a commit to hanzoai/forge that referenced this pull request Jul 26, 2026
- Introduce a “Bypass Protection Allowlist” on branch rules
(users/teams) alongside admins, with BlockAdminMergeOverride
  still respected.
- Surface the allowlist in API (create/edit options, structs) and
settings UI; merge box now shows the red button +
  message for bypass-capable users.
- Apply bypass logic to merge checks and pre-receive so allowlisted
users can override unmet approvals/status checks/
  protected files when force-merging.
- Add migration for new columns, locale strings, and unit tests (bypass
helper; queue test tweak).

<img width="1069" height="218" alt="image"
src="/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL2dvLWdpdGVhL2dpdGVhL3B1bGwvJTNDYSUyMGhyZWY9"/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL3VzZXItYXR0YWNobWVudHMvYXNzZXRzLzBiNjFiYzJhLWEyN2YtNDdmMy1hOTIzLTYxMzY4ODAwOGU2NQ">https://github.com/user-attachments/assets/0b61bc2a-a27f-47f3-a923-613688008e65"
/>


Fixes go-gitea#36476

---------

Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: Giteabot <teabot@gitea.io>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow specific users or teams to bypass branch protection rules (approval/status checks)

6 participants

⌂