Skip to content
GitmoapAPIBeta
Reviewapproval-rules
POST/repositories/{repo_id}/approval-rules

Define an approval rule on a repository.

create_repo_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. A repository's rule cannot be enforced, but it can strengthen a rule a group above enforces.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository 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": {}
}
],
"created_at": "2026-10-08T21:07:12Z",
"defined_at": {
"full_path": "acme/payments-api",
"id": "id-bac4",
"type": "group"
},
"enforcement": "default",
"name": "payments-api",
"required": 3,
"rule_id": "5aadfceb-8f6f-4e5e-bd54-0a733f3bdf47",
"updated_at": "2026-10-08T16:00:10Z",
"applies_to_branches": "applies-to-branches-9253",
"strengthens": "e112cf59-6d1e-4689-9e09-a00e45fa6648"
}
400Invalid request, enforcement asked of a repository, 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-8c3a",
"message": "Inline scalar newtypes but keep their brand"
}
}
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-e8a2",
"message": "Label every synthesized example"
}
}
403The caller cannot manage this repository's rulesapplication/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-c136",
"message": "Draw the region map from operation density"
}
}
404Repository, 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-5d26",
"message": "Draw the region map from operation density"
}
}
409This repository 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-1c75",
"message": "Stream pipeline status into the run header"
}
}
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-0fa4",
"message": "Pin a page's payload to the build that rendered it"
}
}
429Approval rule limit reached for this repositoryapplication/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-0e51",
"message": "Stream pipeline status into the run header"
}
}

CLI

gitmoap approval-rules create-repo-approval-rule

  • --repo-ididRepository ID (id or owner/repo 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