Test a commit message against the full push rule chain, optionally with unsaved edits

POST

/orgs/{org}/push_rules/preview

const url = 'https://gitea.example.com/api/v1/orgs/example/push_rules/preview';
const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'},
  body: '{"author_email":"example","branch_name":"example","default":{"agent_branch_template":"example","agent_exempt":["example"],"author_email":"example","branch_name":"example","description":"example","enabled":true,"example":"example","forbidden":"example","full_message":true,"max_commits":1,"max_file_size_mb":1,"name":"example","prohibited_file_names":"example","required":"example"},"default_mode":"inherit","file_path":"example","mandatory":{"agent_branch_template":"example","agent_exempt":["example"],"author_email":"example","branch_name":"example","description":"example","enabled":true,"example":"example","forbidden":"example","full_message":true,"max_commits":1,"max_file_size_mb":1,"name":"example","prohibited_file_names":"example","required":"example"},"message":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://gitea.example.com/api/v1/orgs/example/push_rules/preview \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "author_email": "example", "branch_name": "example", "default": { "agent_branch_template": "example", "agent_exempt": [ "example" ], "author_email": "example", "branch_name": "example", "description": "example", "enabled": true, "example": "example", "forbidden": "example", "full_message": true, "max_commits": 1, "max_file_size_mb": 1, "name": "example", "prohibited_file_names": "example", "required": "example" }, "default_mode": "inherit", "file_path": "example", "mandatory": { "agent_branch_template": "example", "agent_exempt": [ "example" ], "author_email": "example", "branch_name": "example", "description": "example", "enabled": true, "example": "example", "forbidden": "example", "full_message": true, "max_commits": 1, "max_file_size_mb": 1, "name": "example", "prohibited_file_names": "example", "required": "example" }, "message": "example" }'

Gitea Enterprise only. This endpoint is not part of the community edition.

Authorizations

Parameters

Path Parameters

org

required

string

Name of the organization

Request Body

application/json

PreviewPushRuleOption tests a sample against the full rule chain of a scope. Only the filled sample fields are tested; a request without any of them tests an empty commit message. The default branch exemption of the branch name check is not applied.

Unsaved edits of the rules owned by the scope may be supplied; parent scopes always use their stored rules.

object

author_email

A commit author email to test against the author email checks

string

branch_name

A new branch name to test against the branch name checks

string

default

PushRuleDraft is the unsaved content of one push rule.

object

agent_branch_template

Head branch name for new agent runs when the default name fails a branch name check; {agent} is replaced by the agent name and {issue} by the issue number or “work”

string

agent_exempt

Checks agents may skip: commit_message, branch_name, author_email, file_name, file_size. They cover branches an agent run creates and commits the agent authored, pushed by its run or merged from a pull request it opened

Array<string>

author_email

RE2 expression the author email of every new commit must match

string

branch_name

RE2 expression the name of a newly created branch must match; the default branch is always allowed

string

description

string

enabled

boolean

example

string

forbidden

RE2 expression the commit message must not match

string

full_message

Whether the expressions are matched against the full commit message instead of only its title

boolean

max_commits

Most new commits one push or merge may bring in while the commit checks run; 0 for no limit

integer format: int64

max_file_size_mb

Largest file in MiB a new commit may add or modify; 0 for no limit

integer format: int64

name

string

prohibited_file_names

RE2 expression no file path added or modified by a new commit may match

string

required

RE2 expression the commit message must match

string

default_mode

Unsaved mode of the default rule of an organization or a repository; the stored mode when empty type: string inherit PushRuleModeInherit copy PushRuleModeCopy custom PushRuleModeCustom none PushRuleModeNone

string

Allowed values: inherit copy custom none

file_path

A file path to test against the prohibited file name checks

string

mandatory

PushRuleDraft is the unsaved content of one push rule.

object

agent_branch_template

Head branch name for new agent runs when the default name fails a branch name check; {agent} is replaced by the agent name and {issue} by the issue number or “work”

string

agent_exempt

Array<string>

author_email

RE2 expression the author email of every new commit must match

string

branch_name

RE2 expression the name of a newly created branch must match; the default branch is always allowed

string

description

string

enabled

boolean

example

string

forbidden

RE2 expression the commit message must not match

string

full_message

Whether the expressions are matched against the full commit message instead of only its title

boolean

max_commits

Most new commits one push or merge may bring in while the commit checks run; 0 for no limit

integer format: int64

max_file_size_mb

Largest file in MiB a new commit may add or modify; 0 for no limit

integer format: int64

name

string

prohibited_file_names

RE2 expression no file path added or modified by a new commit may match

string

required

RE2 expression the commit message must match

string

message

string

Responses

200

PreviewPushRuleResult

application/json

PreviewPushRuleResult reports whether a sample would pass every rule of the chain.

object

passed

boolean

results

Array<object>

PushRuleCheckResult reports how one rule of the chain evaluated the previewed sample.

object

checks

The checks the rule configures and the sample fills

Array<object>

PushRuleSampleCheck reports one non-message check of a rule for the previewed sample.

object

kind

Type: string

string

Allowed values: branch_name author_email file_name

boolean

forbidden_ok

boolean

kind

Type: string default PushRuleKindDefault mandatory PushRuleKindMandatory

string

Allowed values: default mandatory

message_tested

Whether the commit message was tested; the message results are true when it was not

boolean

name

string

required_ok

boolean

source

Type: string global PushRuleScopeGlobal org PushRuleScopeOrg repo PushRuleScopeRepo

string

Allowed values: global org repo

source_id

integer format: int64

Example

{
  "results": [
    {
      "checks": [
        {
          "kind": "branch_name"
        }
      ],
      "kind": "default",
      "source": "global"
    }
  ]
}

404

APINotFound is a not found empty response

422

APIValidationError is error format response related to input validation

Headers

message

string

url

string