Collect user feedback: Persisted branch rules design concepts

Context

Branch rules allow users to set up rules to protect the most important code in their repositories. While we have a Branch rules offering today at GitLab, it does not enable teams to protect and manage branches confidently or flexibly at scale — burdening existing customers, limiting growth, and impacting adoption.

A significant number of customers have raised this problem directly through their Customer Success Managers—representing one of the top requests in the Source Code Management category by customer impact. This is a foundational gap in our capabilities. The demand spans both Ultimate and Premium tiers, includes some of our largest customers, and some of these requests have been open for over 6 years—we're committed to addressing these long-standing needs.

Branch Rules #20360 and the Design Vision aims to create a long-term Branch rules solution that will empower teams to protect and manage branches confidently and flexibly at scale. The goal of this research study is to resolve some of the largest unknowns in the Design Vision, and build confidence that the proposed solution will solve long-term needs for users and the business.

User research plan

See [Draft] Branch Rules: Solution validation study plan

Problem & objective

This study has two objectives: conducting contextual inquiry to understand current workflows and identify opportunities, and validating the design to test whether the proposed solution meets user needs.

1. Contextual inquiry

What
- We will observe users' current branch protection workflows to understand how they work today
Goal
- Validate our assumptions about user needs and pain points with branch protections
- Identify process gaps, and automations that can reveal where current tools may not be serving user needs
- Uncover opportunities for future improvements
Priority
- This is a nice-to-have component. It can be deferred if time is constrained, as it's valuable for long-term roadmap planning but not critical for immediate business decisions.

2. Design validation

What
- We will have users complete tasks with the prototype and assess whether it solves their branch protection needs at scale.
Goal
- Design validation
  - Hypothesis: With a policy-like architecture, fixed conflict resolution method (most specific name match, most restrictive), and flexibility tools (include/exclude, bypass, enforceability settings), users will have what they need to balance top-down governance with flexibility for teams when setting up branch rules for their organization.
- Resolving unknowns
  - Rule conflict handling
    - Does a most restrictive, or most specific name match rule conflict resolution model better serve user needs?
  - Inheritance & policy architecture
    - Does a policy-like mental model resolve flexibility and compliance needs at scale?
  - Enforceability
    - Do users need to customize enforceability settings? If so, what level of granularity do they need?
Priority
- This is the primary objective and is required for business decisions moving forward.

Business decisions pending this research

Owner	Decision
@alyssatrinh	General Does the proposed design solution solve major user needs for branch protection at scale? Does the proposed system provide enough tools for flexibility and governance (branch policies, include/exclude patterns, bypass, enforceability) for enterprise customers to effectively manage branch protections at scale?
@alyssatrinh	Rule conflict handling When branch rules conflict, do users expect the “most restrictive” setting to take precedence? When multiple branch rules/policies apply to a branch, should the rules be additive?
@alyssatrinh	Inheritance & policy architecture Does a policy-like architecture serve user needs? Do users actually need to manage branch policies at a group-level? Or do organization-level and project-level branch policies fulfill user needs?
@alyssatrinh	Enforceability Do users need enforceability settings for branch policies? If so, what level of granularity do users need enforceability for (an entire policy, or every individual setting)?

Design questions

ID	Question	Test priority
	General
Q1.1	What are the biggest pain points users struggle with in managing branch protections at scale?	Medium (Already have evidence)
Q1.2	How are customer branch protections set up? What tools do customers use in/outside of GitLab to manage branch protections?	Low (Opportunity)
Q1.3	What automations do users have set up? What unserved needs are users seeking to fulfill with custom automations? How much time do users spend building and maintaining these automations?	Low (Opportunity)
Q1.4	What parts of branch protections do customers prefer to manage with code/API, vs. the GitLab UI? What would be the ideal method for customers to manage branch protections for enterprise?	Low
Q1.5	If we had a system that allowed users to define branch rule targets based on wildcards that could be included and excluded, would that solve customer needs for flexibility?	Low (Already have evidence)
	Rule conflict handling
Q2.1	When users run into a conflict with branch rules, how do they expect the system to resolve the conflict? Why? Can they provide specific examples about why this method solves their needs?	Critical
Q2.2	Which rule conflict model would best serve user needs: most restrictive, or most specific name match? Do users expect the system to always choose the most restrictive individual setting, so their code is better protected? Or do users expect the system to choose the branch rule that has closest naming conventions to the branch name?	Medium (Have strong hypothesis)
Q2.3	In the event of a branch rule conflict, do users expect all settings to be additive (all relevant settings apply)? Or do users expect settings from 1 branch rule to take precedent?	High
	Inheritance & policy architecture
Q3.1	What are enterprise customer needs for top-down enforcement of branch rules? What kinds of branch rules might users want to manage at the top-group or organization level?	Medium
Q3.2	What challenges have customers faced fulfilling needs for top-down enforcement in the current branch rules experience?	Medium
Q3.3	What issues have customers run into with inheritance of branch rules? Have customers experienced issues with the hierarchy when it comes to managing branch protections?	Medium (Already have evidence)
Q3.4	In GitLab today, users define branch rules / protected branch settings for each project/group. [Demo proposed UI] If GitLab introduced a branch policy-like architecture, where users could define a set of branch rules at the organization level, and apply that to various groups/projects as needed, would that solve customer needs for top-down compliance and flexibility? What benefits do customers see from this approach? What concerns would customers have about this approach?	Critical
Q3.5	If we had a policy-like architecture, would customers need to manage policies at a group level? Or are policies defined at the organization and project level enough to serve user needs?	High
	Enforceability
Q4.1	Do users need to customize the enforceability of a branch rule? If so, why? What are some examples where it might be useful to customize enforceability?	High
Q4.2	If users need enforceability, what level of granularity do they need enforceability on? Per entire branch rule Per individual setting	Medium

Assumptions

ID	Assumption	Test priority
	General
A1.1	The current prototype for Branch rules with a policy-like architecture solves user needs for compliance, confidence, scale and flexibility.	Critical
A1.2	When it comes to branch rule management, enterprise users value: compliance, confidence, scale and flexibility.	Low (Already have evidence)
A1.3	GitLab’s current branch rule offering leaves users often unconfident about how branch rules will resolve (in a conflict, across inheritance levels, in respect to other settings, etc).	Low (Already have evidence)
A1.4	Users want to predict how a system will behave so they can construct adequate branch protections at scale.	Low (Already have evidence)
A1.5	Users want to primarily manage branch protections in code, where they can track revisions, collaborate, and manage settings at scale.	Low
A1.6	With wildcards and include/exclude patterns, users will have the flexibility they need to target the branches they need. Full regex is not needed.	Medium
	Rule conflict handling
A2.1	When it comes to the way rule conflicts are handled, users are confused and frustrated with the current rule conflict handling system.	Low (Already have evidence)
A2.2	Having multiple ways of resolving conflicts for different settings is confusing for users to predict and understand.	Low (Already have evidence)
A2.3	Enterprise organizations value compliance and security over developer freedom and velocity.	Low (Already have evidence)
A2.4	Resolving conflicts by choosing the “most permissive” rule conflict does not meet customer needs for compliance and security.	Medium (Already have evidence)
A2.5	When branch rules conflict, users expect the system to choose the “most restrictive” setting.	Critical
A2.6	The root cause of users asking for branch rule conflicts to resolve in “most specific name match” stems from a desire for better control and flexibility for targeting branches in a branch rule. #358910, #39115 (closed), #28048 (closed), #26724 (closed)	High
A2.7	When branch rules conflict, users expect rules to be “additive” (all branch rules that match the target branch will apply).	High
	Inheritance & policy architecture
A3.1	Users want team members with higher permission levels to be able to enforce branch rules that team members with lower permissions.	Low (Already have evidence)
A3.2	Enterprise customers write custom scripts to manage branch protections due to limitations with the current UI to effectively manage governance at scale.	Low (Already have evidence)
A3.3	The current enforcement abilities in the current branch rules system do not allow teams to effectively maintain governance and compliance.	Low (Already have evidence)
A3.4	A policy-like structure for branch rules will allow users to effectively centralize and enforce per-branch settings at scale.	Critical
A3.5	If users can manage branch policies at an organization and project-level, they do not need to have policies specifically scoped to groups.	High
	Enforceability
A4.1	Users want to be able to define whether or not a branch policy needs to be strictly enforced, so they can maintain governance.	High
A4.2	Having enforceability for an entire branch policy is enough to satisfy user needs for governance. Enforceability for individual settings is not needed.	Medium

Problem hypotheses

Hypothesis: With a set rule conflict resolution method (most restrictive, most specific), and a set inheritance model (Cascading settings), and flexibility tools (include/exclude, bypass, enforceability setting), customers will have what they need to balance top-down governance, and flexibility for how their teams work.

Job performer We believe...	Type of task when...	Type of problem experience...
Repository manager	When setting up branch governance for a new group or organization, or onboarding a new project or team	Spend large amounts of time manually configuring branch rules project-by-project, with no ability to enforce settings from the top down Or spend large amounts of time writing custom scripts to manage branch protections at scale
Repository manager	When responding to organizational policy changes that affect large amounts of repositories and developers	Have low confidence that branch rules are set in the way that they expect for governance and compliance. There is no way to confidently verify how settings will resolve for a specific branch.
Repository manager	When responding to a compliance audit and demonstrate specific rules are enforced	Have low confidence that branch rules are set in the way that they expect, and have not been overridden by project maintainers.
Repository manager	When managing exceptions and needing to carve out targeted overrides without breaking broader branch protection strategies	Struggle to enforce governance for organizational rules while maintaining flexibility for teams with varying needs

Solution hypotheses

How we believe the designs being tested will solve user needs/pain points

ID	Feature/Experience/Idea We believe that...	Role/Persona for...	User outcome/Goal will...	Success indicator/Signal We will know this is true when we see	Metric As measured by...	Hypothesis Task
H1	A policy-like architecture that allows users to define branch policies and apply them across groups and projects as needed	Repository managers	Enable them to effectively govern branch protections for their repository at scale, reducing manual configuration, administrative overhead, and gaps in compliance	Users are able to successfully configure an organization-level branch policy in the prototype, have settings cascade down as needed, and have confidence branch protections are configured in the way they expect	Task completion	Task 2: Set up a new organizational branch policy and enforce it at scale
H2	Resolving branch rule conflicts by applying the “most restrictive” setting across all matching rules	Repository managers	Give them a predictable system that favors compliance, giving users confidence their code is protected	Users correctly anticipate how a conflict resolves in the prototype scenario	Accuracy of user prediction of how a conflict will resolve, user feedback on the conflict resolution method	Task 4: Predict how a policy conflict will resolve
H3	Making all branch rule conflicts additive, and using the “most restrictive” conflict resolution method when rules cannot be additive	Repository managers	Allow them to layer compliance requirements from multiple rules in a predictable way	Users correctly anticipate how a conflict resolves in an additive way in the prototype scenario	Accuracy of user prediction of how a conflict will resolve, user feedback on the conflict resolution method	Task 4: Predict how a policy conflict will resolve
H4	Wildcard-based include/exclude patterns for scoping which branches a rule applies to	Repository managers	Provide the flexibility they need to define precise governance boundaries	Users can successfully create a rule with include/exclude patterns in the prototype, articulate the targeting logic correctly, and confirm that this approach would address their needs	Task completion	Task 3: Respond to new organizational compliance requirements
H5	An enforceability setting that allows repository managers to mark a branch policy as non-overridable at the project level	Repository managers	Give them control and confidence over organizational standards, which cannot be weakened by project maintainer workarounds	Users can successfully make a branch policy enforceable in the prototype	Task completion	Task 2: Set up a new organizational branch policy and enforce it at scale
H6	Bypass settings that allow repository managers to define specific actors who are permitted to bypass a branch rule in controlled circumstances	Repository managers	Give them an avenue to flexibly respond to exceptions, and maintain team flexibility without undermining organizational compliance standards	Users can successfully add bypass actors in the prototype	Task completion	Task 3: Respond to new organizational compliance requirements
H7	Providing branch policies at the organization level and project level is sufficient for most enterprise governance needs, and explicit group-level policy management may not be required to solve the core use cases	Repository managers	Still allow them to enforce consistent standards across their repos while bypassing unnecessary complexity in the group layer	Users confirm that organization level + project-level policies are sufficient. Users name a scenario where they must have group-level policies.	Number of participants who raise the need for group-level policies	Task 2: Set up a new organizational branch policy and enforce it at scale
H8	The overall solution (policy-like architecture, most restrictive conflict resolution, include/exclude patterns, bypass settings, enforceability controls)	Repository managers	Give enterprise teams everything they need to govern branch rules with confidence, compliance, flexibility, and scale	Users can successfully complete all tasks	Overall system usability rating	Post-test assessment

Target user groups

ID	Job performer	Number of Participants	Job Titles	Description
U1	Repository manager		Engineering manager, Tech lead, Principal engineer, DevOps engineer, Release manager, Site reliability engineer	The Repository Manager is responsible for establishing and enforcing branch governance policies that protect code quality, security, and compliance across repositories. They operate at the intersection of developer productivity and organizational risk, balancing the need for standardized controls with the flexibility that teams require to ship efficiently.
U2	Code author (out of scope)		Software engineer, Front-end/Back-end/Full-stack engineer, QA engineer, Data engineer	The Code Author is an individual contributor who writes code, opens merge requests, and depends on branch rules being transparent and predictable in order to do their job without unnecessary friction. They don't set the policies, but work within them, and their primary need is clarity: knowing which rules apply to their branch, why a merge is blocked, and what they need to do to move forward.

Test overview

Prototype

Link to share with test participant: [TBD]
Project prototype link (for stakeholders): 🎨 Figma [WIP needs cleanup]

Design Aspects of interest

Overall design concept
Policy-like architecture
Include/exclude patterns
Bypass
Enforceability setting
Auditing tool
Rule conflict management (conceptual mental model)

Test overview

Contextual inquiry

Show or describe current branch protections
Show any automations or workarounds

Prototype tasks

Task 1: First impressions of the interface
- I'm going to show you a new interface. Please don't click on anything yet – just look it over and tell me out loud what you're seeing. Walk me through what you think this page does, and what you'd expect to be able to do here.
Task 2: Set up a new organizational branch policy and enforce it at scale
- Imagine you're the engineering lead at a company with 300 repositories across multiple teams. Your security team has just mandated that all “release/*” branches across your entire organization must require at least 2 approvals from the “My Back-end Developers” group before merging, effective immediately. Using this interface, please set that up.
- Key features
  - Policy architecture
  - Enforceability
Task 3: Respond to new organizational compliance requirements
- Your security team has a new requirement. All “release/*” branches need to require CODEOWNERS approval. However, “release/1.0” is a frozen legacy branch that is managed by a dedicated team and needs to be excluded from this rule. Additionally, your CI/CD service account “deploymentbot” needs to be able to merge directly to “release/*” branches without going through the approval process, so it can handle automated deployments. How would you use this interface to manage these new requirements?
- Key features
  - Include/exclude
  - Bypass
Task 4: Predict how a policy conflict will resolve
- Imagine you have two branch policies that both apply to a branch called “release-v3.” The first policy requires maintainer approval to merge. The second branch policy allows developers to merge.
- Key features
  - Rule conflict management
  - Audit tool

Session Guide

Introduction

Thank you very much for agreeing to participate in this study. Within the next 60 minutes, you will be testing a prototype for a new branch rules system at GitLab. These designs are not final, and because of that, not everything is functional. Please think aloud as you use the designs, so we can learn about your thoughts, impressions, experience and expectations. We would like you to try to use them as if they were final, and whenever you encounter something that doesn’t work or doesn’t behave like you were expecting, please let me know.

Feel free to express positive and negative feedback, my team will not take it personally and it will actually help us iterate on these designs focusing on what needs to be improved. I have a few tasks for you, and I would like you to assume these are real scenarios at work.Do you have any questions before we start?

Basic Profile

Interview Date: Company: Role: Size of Team: Split up of Team Roles:

Developers:
Designers:
Product:
QA:
Geographic Split:

Developer Environment:

IDE:
Source Control:
Communication:
Project Management:

General Questions:

How much time do you spend in GitLab vs. other tools?

Tasks

Materials

Prototype: [TBD]
Zoom link: [TBD]

Pre-task questions / Contextual inquiry

Before we look at anything, I'd love to understand how things work for you today. Can you tell me a bit about how your organization manages branch protections right now?
1. Probe: How many repositories and developers are you managing?
2. Probe: Who is responsible for setting up and maintaining branch rules in your organization?
3. Probe: What's the biggest frustration you have with using GitLab to manage branch protections?
4. Probe: Have you built any workarounds (scripts, automation, manual processes) to manage branch rules at scale? If so, can you show us the workarounds you’ve built?

Prototype tasks

TASK 1: First impressions of the interface
1. Goal: Understand participant reactions to the overall interface before any guidance. Test the policy mental model, terminology, and information architecture.
2. Process:
  1. Prototype screen: [TBD]
  2. Context: I'm going to show you a new interface. Please don't click on anything yet – just look it over and tell me out loud what you're seeing. Walk me through what you think this page does, and what you'd expect to be able to do here.
3. During Task Questions:
  1. Please look over the interface without clicking on it and describe everything you are seeing in different areas of the interface.
  2. Probe: What do you think this tool does?
  3. Probe: At this point, what would you do?
  4. Probe: What stands out to you first?
  5. Probe: Is anything unclear or unexpected?
  6. Probe: What do you think a branch policy means in this context?
4. Post-Task Questions:
  1. How confident do you feel about beginning to use this tool?
  2. Is there anything missing in the design that you would expect?
  3. Is there anything confusing about this interface?
  4. Do you have any concerns about this tool?
  5. What do you think about the terminology used in the design?
TASK 2: Set up a new organizational branch policy and enforce it at scale
1. Goal: Test whether users can successfully create an organization-level branch rule, apply it across a large number of repositories, and use enforceability settings to enforce it. Test user expectations with group-level management.
2. Process:
  1. Prototype screen: [TBD WIP]
  2. Scenario: Imagine you're the engineering lead at a company with 300 repositories across multiple teams. Your security team has just mandated that all “release/*” branches across your entire organization must require at least 2 approvals from the “My Back-end Developers” group before merging, effective immediately. Using this interface, please set that up.
3. During Task Questions:
  1. Probe: Think aloud as you go. What are you looking for?
  2. Probe: What would you need here that you're not seeing?
  3. Probe: If a project maintainer tried to lower the approval requirement to 1, what would you expect to happen?
    - Would you want to prevent that?
    - How do you think you could prevent that using this interface? [Hint: enforceability setting]
  4. Probe after enforceability is configured/discussed: Does this give you what you need, or would you want to control enforceability at a more granular level like per individual setting rather than the whole rule?
  5. User is stuck / can’t complete task:
    - What is missing here that you need?
    - What do you think this area of the design does?
4. Expected Path:
  1. Create new policy
    - Click “Create policy”
    - Policy configurations section > Edit > Policy name = Define a name, Enforcement = “Required” > Save changes
    - Policy target section > “Add” > Include: “release/*” > Save changes
    - Merge request approval rules section > Add > Required number of approvals = 2, Groups = “My Back-end Developers” > Save changes
  2. Apply policy to all groups/projects
    - Click “Targets” tab
    - Select box for “Select all” > “Apply policies” > Select newly created policy > “Apply”
Post-Task Questions:
1. On a scale of 1 to 5, where 1 means not at all easy to use and 5 means very easy to use, how would you rate this system for this task?
  - Why did you choose this rating?
2. How confident are you that this rule would actually be applied and enforced across all 300 repositories?
3. Is there anything about this experience that wouldn't work for how your organization is structured?
4. Is there any information missing in this design that would help you better manage branch protections?
5. Would this tool increase the efficiency of your current workflow?
TASK 3: Respond to new organizational compliance requirements
1. Goal: Test whether users can use include/exclude patterns to target specific branches with precision, and configure bypass settings for legitimate exceptions.
2. Process:
  1. Prototype screen: [TBD WIP]
  2. Scenario: Your security team has a new requirement. All “release/*” branches need to require CODEOWNERS approval. However, “release/1.0” is a frozen legacy branch that is managed by a dedicated team and needs to be excluded from this rule. Additionally, your CI/CD service account “deploymentbot” needs to be able to merge directly to “release/*” branches without going through the approval process, so it can handle automated deployments. How would you use this interface to manage these new requirements?
3. During Task Questions:
  1. Probe: Think aloud as you go. What are you trying to do here?
  2. Probe: What would you need here that you're not seeing?
  3. Probe after they configure the exclude pattern: Can you describe in your own words what branches you think this rule will and won't apply to?
  4. Probe when they reach bypass: Before you configure this, what would you expect to happen if your “deploymentbot” bot tried to merge without bypass enabled?
  5. Probe after configuring bypass: How confident are you that this bypass is controlled enough not to create a security risk? Is there anything you'd want to see to feel confident it's being tracked or audited?
  6. User is stuck / can’t complete task:
    - What is missing here that you need?
    - What do you think this area of the design does?
4. Expected Path:
  1. Click “Policies” tab
  2. Find newly created policy > “Edit”
  3. Merge request approval rules section > Add > Required number of approvals = 1, Groups = “CODEOWNERS” > Save changes
  4. Policy target section > Add > Exclude: “release/1.0” > Save changes
  5. Rule bypass section > Add > Service accounts > “deploymentbot” > Save changes
Post-Task Questions:
1. On a scale of 1 to 5, where 1 means not at all easy to use and 5 means very easy to use, how would you rate this system for this task?
  - Why did you choose this rating?
2. Did the available tools give you the flexibility you needed to complete this task?
  - How does it compare to how you handle this today?
3. Does the include/exclude pattern approach solve the targeting problems you face today?
4. How do you feel about the bypass controls?
  - Is there anything you would expect that you didn’t see here?
5. How confident are you that these changes would be applied and enforced across all 300 repositories?
6. Is there any information missing in this design that would help you better manage branch protections?
7. Would this tool increase the efficiency of your current workflow?
TASK 4: Predict how a policy conflict will resolve
1. Goal: Test whether the most restrictive conflict resolution model meets user expectations, and whether users expect additive behavior across matching rules.
2. Process:
  1. Prototype screen: [TBD WIP]
  2. Scenario: Imagine you have two branch policies that both apply to a branch called “release-v3.” The first policy requires maintainer approval to merge. The second branch policy allows developers to merge.
  3. What do you think the system would do?
    - Which branch policy do you think would win and why?
  4. Now imagine both rules have a status check requirement: one requires a security scan, the other requires a code quality check. Would you expect both checks to apply?
    - Or just the one from whichever rule 'wins'?
    - If both rules had a merge request approval requirement, would you expect both approval rules to apply?
3. During Task Questions:
  1. Probe: Why did you expect it to work that way?
  2. Probe: What would happen to your security posture if the system chose the more permissive rule instead?
  3. Probe: If they say "most specific should win": If a developer could create a more specific rule to bypass a stricter one set by your security team, would that concern you?
4. Expected Path:
  1. The “most restrictive” individual setting would take precedence (unless Enforcement settings were enabled)
Post-Task Questions:
1. On a scale of 1–5, how confident are you in how this system handles rule conflicts?
2. Is the conflict resolution behavior predictable enough that you could reason about it when setting up rules at scale?
3. Does this feel like the right behavior for your organization?
4. Is there any scenario where this would cause a problem for your team?

Follow-up questions

On a scale of 1–5, how would you rate the overall system for managing branch rules at scale?
Thinking about how you manage branch rules today, does the interface solve the biggest problems you face with managing branch protections for your organization?
1. What, if anything, is still missing?
Would you use this?
1. What would need to be true for your organization to adopt this?
2. Do you think your organization be willing to undergo a migration process in order to take advantage of these new features?
Is there anything in this design that surprised you, positively or negatively?
Was there anything that delighted you about any of these UIs?
Was there anything that frustrated you about this interface?
Do you see your team using this branch rules tool in the future?
What are your biggest hesitations about using these tools in your workflow?
1. If there are hesitations, what would this tool need in order for you to adopt it into your workflow?
How do you see this tool impacting the workflow of your team?

End of the session

Closing Remarks
1. Thank you again for participating in this usability test. Your input is very valuable, and helps GitLab evolve its ability to help customers manage branch protections at scale. We appreciate your time and valuable feedback.
Compensation
1. XXX

Recognition of bias

As a note, enterprise customers have various ways of working and feedback from a few large customers is very helpful, but may not represent all use cases. We should be aware of this bias when using this data to make product decisions.

Edited Feb 25, 2026 by Alyssa Trinh