Skip to content
GitmoapAPIBeta
Buildpipeline-runs
POST/repositories/{repo_id}/pipeline-runs

Start a run from a graph that is already resolved

trigger_pipeline_run
  • 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"}

The request carries the whole runnable graph, as a pipeline resolves to. Most callers start a run of a stored pipeline instead, which resolves the graph for them.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository id

Request body

application/json
  • pipeline_idPipelineId (string · uuid)
  • pipeline_namestring
  • pipeline_timeout_secondsinteger · int320–∞
  • resolved_dagResolvedDag
    • The ResolvedDag schema
    • edgesarray of ResolvedEdge
      • The ResolvedEdge schema
      • from_nodeNodeId (string)
      • to_nodeNodeId (string)
      • from_portPortName (string) or nulloptionalAbsent on a dependency-only connection — one that orders two steps and carries nothing.
      • to_portPortName (string) or nulloptionalAbsent on a dependency-only edge.
    • nodesarray of ResolvedNode
      • The ResolvedNode schema
      • capability_idCapabilityId (string)
      • configobjectThe step's own settings, in whatever shape its capability defines. Passed through unread.
      • inputsarray of NodePortSpec
      • max_retriesinteger · int320–∞
      • node_idNodeId (string)
      • outputsarray of NodePortSpec
      • provider_idProviderId (string)
      • provider_imagestringThe container image this step runs. Set by the platform from the capability and version the step resolved to; a value supplied by the caller is ignored.
      • retry_delay_secondsinteger · int320–∞
      • secret_refsarray of SecretRefThe credentials this step needs, named rather than valued — a secret's value never appears here.
      • stage_idStageId (string)
      • stage_indexinteger · int320–∞
      • timeout_secondsinteger · int320–∞
      • allow_failurebooleanoptionalWhether the step is allowed to fail: if it fails or times out, only the steps that depend on it are skipped, and the run ends succeeded_with_warnings rather than failed.
      • approvalManualApproval or nulloptionalThe approval gate on this step itself, if the pipeline put one there. A step can also inherit a gate from the environment it deploys to.
      • cache_enabledbooleanoptionalWhether this step uses the build cache, as its capability declares.
      • cpustring or nulloptionalHow much CPU this step asked for. Unset means the default for its capability.
      • environmentResolvedEnvironment or nulloptionalThe environment this step deploys to, frozen as it was when the run was triggered.
      • image_digeststring or nulloptionalThe exact build of the container image this step runs, when the catalog records one. Pinned, so the step cannot pick up a different build behind the same tag.
      • memorystring or nulloptional
      • namestringoptionalThe step's display name, as the pipeline's author wrote it when the run started. Empty for older runs recorded without one.
      • oidc_federationNodeOidcFederation or nulloptionalThe cloud role this step assumes with a short-lived identity token, when its connection uses OIDC federation. Absent for steps that use only stored credentials.
      • originNodeOrigin or nulloptionalThe component this step came from, when the author wrote a component instance rather than the step itself. Absent for a step the pipeline declares directly.
      • requires_dockerbooleanoptionalWhether this step needs a Docker daemon, as its capability declares.
      • resource_groupResolvedResourceGroup or nulloptionalThe resource group this step holds while it runs, so no other step naming the same group runs at the same time.
      • service_idServiceId (string · uuid) or nulloptionalThe catalog service this step acts on, as it was identified when the run started.
      • variables_fromResolvedEnvironmentVariables or nulloptionalThe environment whose plain variables this step reads without deploying there, as it stood when the run was triggered.
      • versionProviderVersion (string) or nulloptionalThe provider version this step runs: the one the pipeline pins, or else the provider's default version for the repository when the run started. It must be enabled and allowed by the provider policy that applies.
    • stagesarray of ResolvedStage
      • The ResolvedStage schema
      • barrier_modeBarrierModestrictlenientWhen a stage is allowed to start. strict waits for every step in every earlier stage to finish, so a failure anywhere stops what follows. lenient waits only for the steps a given step actually depends on, so an unrelated branch failing does not block it. strict is the default.
      • stage_idStageId (string)
      • stage_indexinteger · int320–∞
    • pipeline_variablesarray of ResolvedPipelineVariableoptionalThe variables available to every step in this run, resolved from the repository and the groups above it when the run was triggered. Changing a variable afterwards does not affect a run already under way, and re-running uses the values the run started with.
      • The ResolvedPipelineVariable schema
      • nameEnvironmentVariableName (string)
      • scope_idstringThe id of the group or repository that declared the variable.
      • valueEnvironmentVariableValue (string) or nulloptional
  • triggerTriggerContext
    • The TriggerContext schema
    • repo_idRepositoryId (string · uuid)
    • repo_pathstring
    • before_shastring or nulloptionalThe commit the ref pointed at before the push — what a paths filter compares against. On a run started by hand, the commit its starter named to compare from, if any.
    • branchstring or nulloptional
    • buildMrBuildTargetmerge_resultsourceor nulloptionalWhich commit a merge-request-triggered run built.
    • commit_shastring or nulloptional
    • depthinteger · int32optional0–∞How many pushes made by pipeline runs led to this run, one after another; 0 when no pipeline's push started it.
    • every_stepbooleanoptionalEvery step runs, whatever its path filter says — asked for by whoever started the run.
    • extraobjectoptionalAdditional fields supplied by whatever started the run, passed along without being interpreted.
    • kindTriggerKindpushmerge_requesttagschedulemanualoptionalWhat started this run.
    • mr_idMergeRequestId (integer · int64) or nulloptional
    • paramsobjectoptionalThe values a person supplied when starting the run, keyed by the parameter names the pipeline's manual trigger declares.
    • ref_namestring or nulloptionalThe full ref (e.g. refs/tags/v1.2.0). Set for runs a tag started, which branch cannot describe.
    • root_group_idGroupId (string · uuid) or nulloptionalThe organisation this run belongs to — the root group of the repository it was triggered for. Recorded when the run starts and never recalculated, so a repository moved to a different organisation part-way through a run keeps the artifacts, logs and cache it has already produced. Absent on runs that started before runs recorded this.
    • schedule_stemstring or nulloptionalWhich scheduled trigger fired, when kind is schedule.
    • source_shastring or nulloptionalThe source-branch commit this run tested: a merge request's source head for a merge-request run, whichever commit it built, and the commit itself for a push or manual run. Set by the platform; absent on a run whose graph the caller supplied, which never counts toward a merge request's pipelines.
    • target_branchstring or nulloptionalThe merge request's target branch.
    • target_shastring or nulloptionalThe target branch's tip this merge-request run was tested against. Once the target branch moves on, the merge check reports a merge-result run as out of date.
    • triggered_byActorSummaryoptionalWho started the run, set by the platform from the authenticated caller; a value supplied in a request is ignored.
    • trustTriggerTrusttrusteduntrustedoptionalWhether the code being built is trusted with the repository's connections and secrets. Set by the platform when the run starts, whatever a request says.
    • trust_reasonTrustReason or nulloptionalWhy the run has the trust it has: who wrote the code, a person's merge or approval, or the organization's AI configuration. Absent on runs that started before this was recorded.
Request body exampleSynthesized example
{
"pipeline_id": "8baedb85-49ab-4e35-afdd-135235d3fead",
"pipeline_name": "payments-api",
"pipeline_timeout_seconds": 51,
"resolved_dag": {
"edges": [
{
"from_node": "from-node-c984",
"to_node": "to-node-6bcc"
},
{
"from_node": "from-node-cb56",
"to_node": "to-node-80a6"
}
],
"nodes": [
{
"capability_id": "1141162c-30df-4927-972d-dcd037a8ce28",
"config": {},
"inputs": [],
"max_retries": 80,
"node_id": "6dba77da-9c22-4af7-902a-af75a1649ca5",
"outputs": [],
"provider_id": "4f2c7558-b147-4d63-a23b-542a729f02a6",
"provider_image": "provider-image-f5d2",
"retry_delay_seconds": 59,
"secret_refs": [],
"stage_id": "ee45a9cb-abdd-4aae-a5cc-4dca669d9e0e",
"stage_index": 5,
"timeout_seconds": 24
},
{
"capability_id": "c4298110-4956-4302-882d-ec42f39f64ae",
"config": {},
"inputs": [],
"max_retries": 88,
"node_id": "5093d6bd-d962-4e7c-bc16-41a2f2d99fee",
"outputs": [],
"provider_id": "909dc1f4-479e-4973-b6b0-8e553af0a9b9",
"provider_image": "provider-image-2475",
"retry_delay_seconds": 88,
"secret_refs": [],
"stage_id": "ef21c376-6756-4326-b045-d1f924e1a5c3",
"stage_index": 4,
"timeout_seconds": 2
}
],
"stages": [
{
"barrier_mode": "strict",
"stage_id": "b446e226-c47b-4b50-8e39-c248df3b549a",
"stage_index": 6
},
{
"barrier_mode": "strict",
"stage_id": "c7ff1134-a10a-44b3-af15-843f72c7d5ec",
"stage_index": 1
}
]
},
"trigger": {
"repo_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70",
"repo_path": "repo-path-f818"
}
}

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": "5cf1af80-388d-4e88-a6a3-573942f98bb2",
"pipeline_run_id": "9e2b7c41-3d5a-4f8e-b1c2-7a6d5e4f3c2b",
"repo_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70",
"started_at": "2026-10-14T14:44:23Z",
"status": "running"
}
400Invalid request body, a trigger.repo_id that does not match the path, a graph too large for one run, or a step reading a variable that is undeclared or secretapplication/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
  • VALIDATION_ERRORA value is outside what the operation accepts; the message says which
  • 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-a76e",
"message": "Inline scalar newtypes but keep their brand"
}
}
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-6f81",
"message": "Stream pipeline status into the run header"
}
}
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-fbbe",
"message": "Draw the region map from operation density"
}
}
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-83a3",
"message": "Stream pipeline status into the run header"
}
}
409The request conflicts with the resource's current state; `reason` says howapplication/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-8455",
"message": "Label every synthesized example"
}
}
429Pipeline compute quota reached for this namespaceapplication/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-2b3d",
"message": "Label every synthesized 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
{
"error": {
"code": "code-52c4",
"message": "Pin a page's payload to the build that rendered it"
}
}

CLI

gitmoap pipeline-runs trigger

  • --repo-ididRepository id (id or owner/repo path)
  • --pipeline-idstring
  • --pipeline-namestring
  • --pipeline-timeout-secondsnumber
  • --resolved-dagjson
  • --triggerjson

Used in these guides