Skip to content
GitmoapAPIBeta
Buildpipelines
POST/repositories/{repo_id}/pipelines/{pipeline_id}/trigger

Trigger a run from a stored pipeline definition.

trigger_pipeline
  • pipeline:trigger
    A token needs the pipeline:trigger scope: Trigger and validate pipeline runsGranted by write_api, write_repository.Every operation this scope unlocks
  • Audited · mutation

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

  • Quota · pipeline compute

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

Starts a run of a published pipeline. The pipeline is resolved into a runnable graph and the run built at the branch's current tip, or at exactly the commit you name. A manual trigger's parameters are checked before the run starts, so a misspelled or ill-typed one is refused straight away. A draft cannot be run.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository id
  • pipeline_idPipelineId (string · uuid)Pipeline definition id

Request body

application/json
  • every_stepbooleanoptionalRun every step, whatever its path filter says. By default a step that deploys runs only if something it watches changed since its environment's last deploy, and any other filtered step runs when a step after it does.
  • pipeline_timeout_secondsinteger · int32 or nulloptional0–∞The run's overall time limit, in seconds. Absent or 0 uses the platform default.
  • sinceCommitHash (string) or nulloptionalCompare from this commit: a step that does not deploy runs only if something it watches changed between this commit and the one being built. Absent, such a step runs when a step after it does.
  • triggerTriggerInputoptional
    • The TriggerInput schema
    • branchstring or nulloptional
    • commit_shastring or nulloptional
    • extraobjectoptional
    • kindTriggerKindpushmerge_requesttagschedulemanualoptionalWhat kind of event started the run. Defaults to manual.
    • mr_idMergeRequestId (integer · int64) or nulloptional
    • paramsobjectoptionalValues for the parameters the pipeline's manual trigger declares, by name. They are checked against the declared parameters before the run starts, and only these can be read from a step's config — unlike extra, which is passed along as given.
Request body exampleSynthesized example
{}

Responses

201Pipeline run createdapplication/json
  • pipeline_idPipelineId (string · uuid)
  • pipeline_run_idPipelineRunId (string · uuid)
  • repo_idRepositoryId (string · uuid)
  • started_atstringWhen the run started, RFC 3339.
  • statusPipelineStatusrunningsucceededsucceeded_with_warningsfailedtimed_outcancelledPer-PipelineRun status.
201 exampleSynthesized example
{
"pipeline_id": "d5acda7c-ca2f-4b33-bf6f-0be280b5d5bd",
"pipeline_run_id": "9e2b7c41-3d5a-4f8e-b1c2-7a6d5e4f3c2b",
"repo_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70",
"started_at": "2026-10-10T00:45:06Z",
"status": "running"
}
400Resolution failure (unknown capability, unwired input, missing connection, a step reading a variable that is undeclared or secret, …)application/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • PIPELINE_VALIDATION_FAILEDThe pipeline definition is invalid; violations lists every problem, so all of them can be fixed at once
  • 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-29a2",
"message": "Label every synthesized 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
{
"error": {
"code": "code-d8fa",
"message": "Pin a page's payload to the build that rendered it"
}
}
403application/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
  • PROVIDER_VALIDATION_FAILEDThe pipeline uses a provider your organization's policy does not allow; violations lists each one
  • 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-84bb",
"message": "Inline scalar newtypes but keep their brand"
}
}
404application/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-abfb",
"message": "Stream pipeline status into the run header"
}
}
409Pipeline is a draft and cannot be triggeredapplication/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
  • 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-ba93",
"message": "Inline scalar newtypes but keep their brand"
}
}
429Namespace compute quota exceededapplication/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-1e29",
"message": "Label every synthesized example"
}
}
500Pipelines are not fully configured on this deploymentapplication/json
Error codes
  • INTERNAL_ERRORRetryableThe server failed; retry, and report it if it persists
  • 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.
500 exampleSynthesized example
{
"error": {
"code": "code-1fc0",
"message": "Inline scalar newtypes but keep their brand"
}
}

CLI

gitmoap pipelines trigger

  • --repo-ididRepository id (id or owner/repo path)
  • --pipeline-ididPipeline definition id
  • --every-stepflagoptionalRun every step, whatever its path filter says. By default a step that deploys runs only if something it watches changed since its environment's last deploy, and any other filtered step runs when a step after it does.
  • --pipeline-timeout-secondsnumberoptionalThe run's overall time limit, in seconds. Absent or `0` uses the platform default.
  • --sincestringoptional
  • --triggerjsonoptional

Used in these guides