Skip to content
GitmoapAPIBeta
Reviewapproval-rules
POST/groups/{group_id}/approval-rules

Define an approval rule on a group, for every repository beneath it.

create_group_approval_rule
  • approval_rule:manage
    A token needs the approval_rule:manage scope: Define, change and delete approval rules, and set the approval policyGranted by write_api.Every operation this scope unlocks
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

  • Quota · approval rules per scope

    x-gitmoap-quota: {"kind":"enforced","arg":"approval_rules_per_scope"}

A rule requires 1 to 10 approvals before a merge request into the matching branches can merge, from approvers you name — people, teams, a role at a group or repository, code owners, or anyone who may approve — and says which kinds of approval count. Maintainers and above may define one; an enforced rule, which applies beneath and may only be strengthened there, needs an Owner. Name an enforced rule from above in strengthens to replace it here with a rule at least as strong.

Parameters

Path
  • group_idGroupId (string · uuid)Group ID

Request body

application/json
  • nameApprovalRuleName (string)
  • accept_fromAcceptFrompeople_signed_inpeoplepeople_and_service_accountspeople_and_agentsoptionalWhich kinds of approval count toward a rule.
  • applies_to_branchesBranchPattern (string) or nulloptionalA branch pattern such as main or release/*; absent means every branch.
  • approversarray of ApproverRef or nulloptionalWho may satisfy it. Absent means anyone who may approve merge requests here.
  • enforcementRuleEnforcementdefaultenforcedoptionalenforced applies the rule to everything beneath and lets it only be strengthened there. Only someone who administers access here may define one.
  • requiredinteger · int32optional0–∞Distinct approvals that must count, 1–10.
  • strengthensApprovalRuleId (string · uuid) or nulloptionalAn enforced rule defined above, to strengthen here: this rule then applies in its place, and must be at least as strong in every field.
Request body exampleSynthesized example
{
"name": "payments-api"
}

Responses

201The ruleapplication/json
  • accept_fromAcceptFrompeople_signed_inpeoplepeople_and_service_accountspeople_and_agentsWhich kinds of approval count toward a rule.
  • approversarray of ApproverRef
  • created_atstring · date-time
  • defined_atAccessScopeThe group or repository that defines it.
  • enforcementRuleEnforcementdefaultenforcedWhether the scopes beneath may replace a rule, or only strengthen it.
  • namestring
  • requiredinteger · int320–∞Distinct approvals that must count, 1–10.
  • rule_idApprovalRuleId (string · uuid)
  • updated_atstring · date-time
  • applies_to_branchesBranchPattern (string) or nulloptionalThe branches whose merge requests this rule applies to; absent means every branch.
  • strengthensApprovalRuleId (string · uuid) or nulloptionalThe enforced rule above this one that it strengthens, in whose place it applies here and beneath.
201 exampleSynthesized example
{
"accept_from": "people_signed_in",
"approvers": [
{
"anyone": {}
},
{
"anyone": {}
}
],
"created_at": "2026-10-15T22:28:35Z",
"defined_at": {
"full_path": "acme/payments-api",
"id": "id-da18",
"type": "group"
},
"enforcement": "default",
"name": "payments-api",
"required": 23,
"rule_id": "f3ffc8b4-6085-4070-ab86-28a5fac5476f",
"updated_at": "2026-10-15T04:23:21Z",
"applies_to_branches": "applies-to-branches-cd49",
"strengthens": "0b4dd13f-6fd5-45ec-8f0a-94f18f718105"
}
400Invalid request, or `strengthens` names no enforced rule aboveapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-60dc",
"message": "Stream pipeline status into the run header"
}
}
401Authentication requiredapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-d39d",
"message": "Pin a page's payload to the build that rendered it"
}
}
403The caller cannot manage this group's rules, or cannot enforce themapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-9851",
"message": "Inline scalar newtypes but keep their brand"
}
}
404Group, team or approver scope not foundapplication/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-b236",
"message": "Pin a page's payload to the build that rendered it"
}
}
409This group already strengthens that ruleapplication/json
Error codes
  • CONFLICTThe request conflicts with the resource's current state; reason says how
  • LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open
  • RULE_ALREADY_STRENGTHENEDThis group or repository already strengthens that rule; change that rule instead
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
409 exampleSynthesized example
{
"error": {
"code": "code-79fd",
"message": "Pin a page's payload to the build that rendered it"
}
}
422The rule would be weaker than the enforced rule it strengthensapplication/json
Error codes
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
422 exampleSynthesized example
{
"error": {
"code": "code-2d1a",
"message": "Pin a page's payload to the build that rendered it"
}
}
429Approval rule limit reached for this groupapplication/json
Error codes
  • TOO_MANY_REQUESTSRetryableA quota, a rate limit or a transfer budget is spent. When the response carries Retry-After, retry after that many seconds
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
429 exampleSynthesized example
{
"error": {
"code": "code-69ea",
"message": "Label every synthesized example"
}
}

CLI

gitmoap approval-rules create-group-approval-rule

  • --group-ididGroup ID (id or group path)
  • --accept-frompeople_signed_in | people | people_and_service_accounts | people_and_agentsoptional
  • --applies-to-branchesstringoptional
  • --approversjsonoptionalWho may satisfy it. Absent means anyone who may approve merge requests here.
  • --enforcementdefault | enforcedoptional`enforced` applies the rule to everything beneath and lets it only be strengthened there. Only someone who administers access here may define one.
  • --namestring
  • --requirednumberoptionalDistinct approvals that must count, 1–10.
  • --strengthensstringoptional

Used in these guides