Push Rules

Push rules let you enforce commit conventions on the server. A push that violates a rule is rejected before it lands, with a message that names the commit, the rule and the reason. Push rules are available in Gitea Enterprise v27.3.8 and later and need a valid license to be changed.

What can be checked

Check	Description
Required pattern	The commit message must match this RE2 regular expression, for example a ticket ID followed by a summary.
Forbidden pattern	The commit message must not match this RE2 regular expression.
Match the full commit message	By default only the title (first line) is matched. Enable it to match the whole message.
Branch name	The name of a newly created branch must match the pattern. Existing branches and the default branch are always allowed.
Commit author email	The author email of every new commit must match the pattern, for example your company domain.
Prohibited file names	A new commit must not add or modify a file whose path matches the pattern.
Maximum file size	A new commit must not add or modify a file larger than this many MiB. Files in Git LFS are not affected because only their small pointer is committed. 0 means no limit.
Maximum new commits per push	The most new commits one push or merge may bring in while the commit checks run. A bigger one is refused and has to be split. 0 means no limit, and the smallest limit wins when several rules set one.

A rule can be given a name, a description and an example. They are shown in the rejection message, so developers learn what format is expected.

To fill in the commit message pattern quickly, tick one or more of the Allowed formats (ticket ID and summary, Conventional Commits with ticket ID, Revert, Merge branch) and click Fill. Review the generated pattern before saving; nothing is enforced until the rule is saved and enabled.

What is not checked

Only commits that are newly introduced on branches are checked, and branch names only when a branch is created. Tag-only pushes, wiki pages, imported history and system-generated commits are not checked.

Where to configure

Scope	Location
Instance	Site Administration > Push Rules
Organization	Organization > Settings > Push Rules
Repository	Repository > Settings > Push Rules

Each scope offers two kinds of rules.

Mandatory rule

A mandatory rule applies to every push in its scope and cannot be disabled at a lower level. An instance mandatory rule applies to all repositories, and an organization mandatory rule to all repositories of that organization. Repository settings only show the mandatory rules that are enforced, read-only, together with their source (Instance, Organization or Repository). Ask an instance administrator or an organization owner to change them.

Default rule

A default rule applies unless a lower level opts out. The instance default rule applies to every repository that does not opt out. Organizations and repositories choose a Mode:

Mode	Behavior
Inherit	Follow the parent rule and stay in sync with it.
Copy	Take a snapshot of the parent rule that can then be edited independently.
Custom	Define a rule for this scope only.
None	Disable the default rule for this scope, even if a parent rule is enabled.

The page shows which default rule is currently effective. Mandatory rules always apply on top of the default rule.

When a repository that keeps its own push rule is transferred, review that rule against the new owner’s mandatory rules.

Test a rule

The Test push rules section on each page evaluates a sample commit message, new branch name, author email or file path against the effective rules, including unsaved changes in the forms. Only the filled fields are tested. Use it to verify a pattern before enabling it.

Rejected pushes

A rejected push lists the first rejected commits with the rule that failed, for example:

Commit message does not meet the requirements.
2 commit(s) rejected, showing the first 2:
Mandatory rule "Ticket ID": the message does not match the required format.
Example: PROJ-123 fix login redirect

The check looks at up to a bounded number of new commits per write. When a push is larger, split it. When the default merge message of a pull request does not satisfy the commit message rules, edit the merge title before merging, or add a compliant template such as .gitea/default_merge_message/MERGE_TEMPLATE.md to the base branch.

Agents

Agents follow every other check of a push rule: Gitea hands the rule to an agent before it works so that it can test against it. A rule can let agents skip selected checks (commit message, branch name, author email, prohibited file names, maximum file size). A skipped check only covers branches an agent run creates and commits the agent authored itself, and every write that uses it is audited. For the branch name check you can also set an Agent branch name template with the {agent} and {issue} placeholders (work stands for a missing issue) so that agent branches satisfy the rule. An agent whose branch name is refused does not start.

Audit

Changes to push rules, and writes that skip push rules (including the checks an agent skips), are written to the audit log.