POST/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/approvals/{node_id}

Grant or deny a pipeline step waiting at its approval gate.

approve_node

pipeline:approve
A token needs the pipeline:approve scope: Grant or deny a pipeline node waiting at an approval gateEvery operation this scope unlocks
Audited · mutation
x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

The decision is accepted here and applied a moment later, exactly as cancel and retry are — poll the run to see the step move.

Parameters

Path

repo_idRepositoryId (string · uuid)Repository id
pipeline_run_idPipelineRunId (string · uuid)Pipeline run id
node_idNodeId (string)Node awaiting approval

Request body

application/json

decisionApproveNodeDecisiongrantdenyYour decision on a step waiting for approval: grant counts towards letting it run, deny stops it.
commentstring or nulloptionalAn optional note from the approver. Shown with the decision, and on a denial it is also shown on the step, so why a deploy did not happen is visible where the run is.

Request body exampleSynthesized example

Responses

202Decision acceptedapplication/json

approvals_receivedinteger · int320–∞Distinct approvals given so far, this one included.
approvals_requiredinteger · int320–∞Distinct approvals the gate needs before the step starts.
decisionApproveNodeDecisiongrantdenyYour decision on a step waiting for approval: grant counts towards letting it run, deny stops it.
event_idEventId (string · uuid)
node_idNodeId (string)
pipeline_run_idPipelineRunId (string · uuid)

202 exampleSynthesized example

400Bad request — a path parameter is not a well-formed value of its typeapplication/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

401application/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

403Not an approver, an approval this gate does not accept, or self-approval is forbiddenapplication/json

Error codes

APPROVAL_NOT_ACCEPTEDThis approval gate does not count your approval
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
NOT_AN_APPROVERYou may not approve this step
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
SELF_APPROVAL_FORBIDDENThe environment does not let the person who started a run approve 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

404Run or node 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

409The node is not awaiting approval, or the caller has already approved itapplication/json

Error codes

ALREADY_APPROVEDYou have already approved this step; it needs approvals from other people
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
NOT_AWAITING_APPROVALThe step is not waiting for an approval

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

501Pipelines are not configured on this deploymentapplication/json

Error codes

NOT_IMPLEMENTEDThis deployment has not configured the feature the operation needs; 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.

501 exampleSynthesized example

CLI

gitmoap pipeline-runs approve-node

--repo-ididRepository id (id or owner/repo path)
--pipeline-run-ididPipeline run id
--node-ididNode awaiting approval
--commentstringoptionalAn optional note from the approver. Shown with the decision, and on a denial it is also shown on the step, so why a deploy did not happen is visible where the run is.
--decisiongrant | deny

Used in these guides

Pipelines

Request

curl -X POST "https://api.gitmoap.com/repositories//pipeline-runs//approvals/" \
  -H "Authorization: Bearer $GITMOAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": ""
  }'

gitmoap pipeline-runs approve-node \
  --repo-id  \
  --pipeline-run-id  \
  --node-id  \
  --decision

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.POST("/repositories/{repo_id}/pipeline-runs/{pipeline_run_id}/approvals/{node_id}", {
  params: {
    path: { repo_id: "", pipeline_run_id: "", node_id: "" },
  },
  body: {
    decision: ""
  },
});

POST /repositories//pipeline-runs//approvals/ HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN
Content-Type: application/json

{
  "decision": ""
}

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.