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

New Issue

GiteaMirror · 2025-11-02T11:18:27-06:00

GiteaMirror commented

2025-11-02 11:18:27 -06:00

Originally created by @MuhmdHsn313 on GitHub (Jun 22, 2025).

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.

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

Originally created by @MuhmdHsn313 on GitHub (Jun 22, 2025). ### 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: ```yaml 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: ```bash 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: ```yaml 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](https://github.com/go-gitea/gitea/issues/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_

GiteaMirror added the type/proposal label 2025-11-02 11:18:27 -06:00

GiteaMirror commented

2025-11-02 11:18:28 -06:00

@MuhmdHsn313 commented on GitHub (Jul 11, 2025):

Dear @lunny
Could you review my proposal?

@MuhmdHsn313 commented on GitHub (Jul 11, 2025): Dear @lunny Could you review my proposal?

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#14634

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