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 thepipeline:triggerscope: Trigger and validate pipeline runsGranted bywrite_api,write_repository.Every operation this scope unlocksAudited · 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_warningsrather thanfailed. - 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.
strictwaits for every step in every earlier stage to finish, so a failure anywhere stops what follows.lenientwaits only for the steps a given step actually depends on, so an unrelated branch failing does not block it.strictis 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
pathsfilter 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;
0when 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, whichbranchcannot 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
kindisschedule. - 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.
- The ActorSummary schema
- emailstring
- idstring
- usernamestring
- avatar_urlstring or nulloptional
- 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-
PipelineRunstatus.
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;
violationslists 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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;
reasonnames the permission or the rule that refused it - INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs;
required_scopenames 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;
violationslists 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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;
reasonsays 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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
reasonorcode. - fieldstring or nulloptionalOn a
400that 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 oncodeotherwise. - required_scopestring or nulloptionalThe scope the access token was missing, on
INSUFFICIENT_SCOPE. - violationsanyoptionalPresent on the structured-validation errors (
PROVIDER_VALIDATION_FAILEDper-node,PIPELINE_VALIDATION_FAILEDDAG): 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