Proposal: Policy-Driven Custom Branching Models with CLI, Regex, and Organizational Enforcement

[MuhmdHsn313]

Feature Description

Summary

This proposal introduces a comprehensive and extensible branching model system in Gitea. The feature allows repository, team, and organization administrators to define custom branching models with rules for naming, branch flow, and protection. It supports inheritance across organization → team → repository levels and includes CLI integration and advanced automation features like regex validation, lifecycle hooks, and "warn mode" enforcement.

The goal is to support both structured workflows like GitFlow and customizable team-defined branching strategies—bringing Gitea on par with, and even beyond, GitHub, GitLab, and Bitbucket.

---

Goals

• Enable repositories to define custom branching strategies.
• Enforce prefix, base, and merge rules.
• Prevent accidental deletion of protected branch types.
• Support organizational-level branching policy enforcement.
• Provide advanced automation via CLI, lifecycle hooks, and integration with issue trackers.
• Allow extensibility with templates (e.g., GitFlow, Trunk Based).
• Allow soft enforcement via "warn mode" to ease policy adoption.

---

Feature Overview

Repository-Level Configuration

Each repository can optionally define a branching model:

branching_model:
  enabled: true
  enforce: true
  types:
    - name: feature
      prefix: feature/
      base: develop
    - name: release
      prefix: release/
      base: develop
  rules:
    enforce_prefix: true
    enforce_base: true
    enforce_merge:
      - from: release/*
        to: main, develop

---

Organizational & Team Enforcement

• Organizations and teams can define default branching models.
• Admins may enforce models to be used across all child repositories.
• Inheritance: organization > team > repository
• Admins can lock certain rules from being overridden.

---

Templates Support

• GitFlow, GitHub Flow, Trunk-Based templates.
• Repositories can import a template and customize it.
• Future extensibility: template registry or community sharing.

---

Validation & Protection Features

• Regex naming validation per branch type.
• "Warn" enforcement mode: log violations without blocking.
• Prevent deletion of protected branch types (e.g., release/*).
• Pull request direction enforcement.

---

Web UI Integration

• Repo Settings: Enable/Disable, template select, rule builder.
• Branch creation: Select type → auto-generate name → validate.
• Pull Request UI: indicate if the branch violates the model.

---

Gitea CLI (tea) Support

Commands to support branching models via CLI:

tea repo branch-types
tea repo branch create --type feature --name login-page
tea repo branch validate --name hotfix/security-001
tea repo branch-policy show

This enables developers using terminals or automation pipelines to stay compliant.

---

Lifecycle Automation (Hooks)

Example:

lifecycle_hooks:
  on_create:
    feature/*:
      trigger: run-ci
  on_merge:
    hotfix/*:
      trigger: create-release-tag

These hooks can call webhooks, CI systems, or future internal automation modules.

---

Issue Tracker Integration

• Auto-fill branch names from issue keys.
• Validate branch names to be linked to issues.
• Link PRs automatically to issues and milestones.

---

Benefits

• Brings Gitea closer to enterprise Git standards.
• Enables workflow consistency across teams and organizations.
• Reduces human error via validation and protection.
• Helps teams transition gradually with warn mode.
• Supports both UI-based and CLI-based interaction.
• Modular design allows future expansion.

---

Related Proposal

This proposal is an evolution of Issue #26164, which suggested support for branch types and prefixing. Here we expand the idea into a comprehensive, policy-driven system.

---

Suggested Implementation Plan

• Schema and model definitions (repo/org/team configs)
• API endpoints and policy enforcement backend
• UI for repository settings and branch creation
• CLI enhancements via tea
• Hook mechanism and validation engine
• Templates and docs

Screenshots

No response