# Org-Level Branch Protection API

## Overview

MokoGitea v1261.0.0 introduces **organization-level branch protection rulesets** that cascade automatically to all repositories within an organization. This eliminates the need to configure identical branch protection rules on each repo individually.

## How Inheritance Works

1. **Repo rules take precedence** — If a repo has its own protection rule for a branch pattern (e.g., `main`), the org rule is ignored for that repo.
2. **Org rules are the fallback** — If no repo-level rule matches a branch, the system checks org-level rules.
3. **Team-based only** — Org rules reference teams, not individual users (use repo-level rules for per-user whitelists).

## API Endpoints

All endpoints require authentication (`token`) and org ownership permissions.

### List Rules

```
GET /api/v1/orgs/{org}/branch_protections
```

### Create Rule

```
POST /api/v1/orgs/{org}/branch_protections
```

**Body:**
```json
{
  "rule_name": "main",
  "enable_push": true,
  "enable_push_whitelist": true,
  "push_whitelist_teams": ["developers"],
  "enable_merge_whitelist": true,
  "merge_whitelist_teams": ["maintainers"],
  "required_approvals": 2,
  "block_on_rejected_reviews": true,
  "block_on_outdated_branch": true,
  "dismiss_stale_approvals": true,
  "require_signed_commits": false
}
```

### Get Rule

```
GET /api/v1/orgs/{org}/branch_protections/{name}
```

### Update Rule

```
PATCH /api/v1/orgs/{org}/branch_protections/{name}
```

Only fields included in the request body are updated.

### Delete Rule

```
DELETE /api/v1/orgs/{org}/branch_protections/{name}
```

## Glob Patterns

Rule names support glob patterns for matching multiple branches:

| Pattern | Matches |
|---------|---------|
| `main` | Exactly `main` |
| `dev` | Exactly `dev` |
| `rc/*` | `rc/1.0`, `rc/2.0-beta`, etc. |
| `beta/*` | `beta/feature-x`, etc. |
| `release/**` | `release/v1`, `release/v1/hotfix`, etc. |

## Example: Protect All Standard Branches

```bash
TOKEN="your-token"
ORG="MokoConsulting"
API="https://git.mokoconsulting.tech/api/v1"

for BRANCH in main dev "rc/*" "beta/*" "alpha/*"; do
  curl -X POST "$API/orgs/$ORG/branch_protections" \
    -H "Authorization: token $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"rule_name\": \"$BRANCH\",
      \"enable_push\": true,
      \"enable_push_whitelist\": true,
      \"push_whitelist_teams\": [\"developers\"],
      \"required_approvals\": 1,
      \"block_on_rejected_reviews\": true,
      \"block_on_outdated_branch\": true
    }"
done
```

## Configuration: Help & Support URLs

Also new in v1261.0.0 — configurable help/support links in `app.ini`:

```ini
[DEFAULT]
HELP_URL = https://docs.mokoconsulting.tech
SUPPORT_URL = https://mokoconsulting.tech/support
```

These replace the hardcoded `docs.gitea.com` links in the navigation bar and are visible in **Site Admin > Configuration**.

## Version Convention

MokoGitea uses `1261.xx.xx` versioning where `1261` represents the fork starting point from upstream Gitea. Minor and patch numbers track MokoGitea-specific releases.
