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

Check whether a run would be allowed, without starting it.

validate_pipeline_run

Applies the repository's effective provider settings — which providers are enabled, and which of their versions the policy admits — and answers with the image each node would run, or with what is in the way. No run is created.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository id

Request body

application/json
  • 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
Request body exampleSynthesized example
{
"resolved_dag": {
"edges": [
{
"from_node": "from-node-e300",
"to_node": "to-node-248c"
}
],
"nodes": [
{
"capability_id": "0f9400be-52f1-4ef9-8c41-edc25d203622",
"config": {},
"inputs": [],
"max_retries": 44,
"node_id": "e471b638-25c0-4d50-89fb-f65a699854f0",
"outputs": [],
"provider_id": "b28345c0-6ee8-4112-8231-9f75cbe29527",
"provider_image": "provider-image-a184",
"retry_delay_seconds": 81,
"secret_refs": [],
"stage_id": "035191c0-5d1a-4558-a66b-221252f9fabc",
"stage_index": 6,
"timeout_seconds": 43
}
],
"stages": [
{
"barrier_mode": "strict",
"stage_id": "141cbbcd-6dd7-40a9-a807-57dc9a6e5977",
"stage_index": 5
},
{
"barrier_mode": "strict",
"stage_id": "fc592e5b-cec0-480a-9ba4-f2125ea504a8",
"stage_index": 1
}
]
}
}

Responses

200Validation report (valid flag + resolved bindings or violations)application/json
  • resolvedarray of ResolvedNodeImage
    • The ResolvedNodeImage schema
    • cache_enabledboolean
    • capability_idCapabilityId (string)
    • default_timeout_secondsinteger · int320–∞
    • image_uristring
    • node_idNodeId (string)
    • provider_idProviderId (string)
    • requires_dockerboolean
    • resolved_versionProviderVersion (string)
    • version_sourceVersionSourcenodegroup_defaulttrack_latestWhere a step's provider version came from: node (the step pins it), group_default (the default version set for the repository or a group above it) or track_latest (the latest published version when the run started).
    • image_digeststring or nulloptional
  • validboolean
  • violationsarray of ProviderViolation
    • The ProviderViolation schema
    • codeViolationCodeprovider_not_enabledprovider_disabledprovider_tier_not_acceptedprovider_version_unspecifiedprovider_version_not_allowedprovider_version_not_in_catalogcapability_not_in_versionprovider_version_sunsetprovider_namespace_not_verifiedprovider_private_foreign_orgWhy steps failed the provider checks made when a run starts. Each code is stable: match on the code, never on the message.
    • detailstring
    • node_idsarray of NodeId (string)
    • provider_idProviderId (string)
    • allowedVersionPolicy or nulloptionalThe version policy that refused requested_version, when that is the cause.
    • capability_idCapabilityId (string) or nulloptional
    • denying_scope_idstring or nulloptionalThe id of the group or repository where the provider is disabled, when that is the cause.
    • requested_versionProviderVersion (string) or nulloptional
  • warningsarray of ProviderWarningoptional
    • The ProviderWarning schema
    • codeWarningCodeprovider_version_deprecatedprovider_version_sunset_pendingAn advisory about a step's provider version that does not stop the run: provider_version_deprecated (the version still runs but is discouraged) or provider_version_sunset_pending (the version is sunset and its grace period is running out).
    • detailstring
    • node_idsarray of NodeId (string)
    • provider_idProviderId (string)
    • requested_versionProviderVersion (string) or nulloptional
200 exampleSynthesized example
{
"resolved": [
{
"cache_enabled": false,
"capability_id": "a9d0cd81-58e3-4829-a6bf-cd13227503d2",
"default_timeout_seconds": 41,
"image_uri": "https://gitmoap.example/acme/2edf6595",
"node_id": "c655becc-6cc1-4698-885b-a3f29d73c277",
"provider_id": "c1fedf0b-e907-45c5-bef2-a62c28e4f370",
"requires_docker": false,
"resolved_version": "resolved-version-d9b2",
"version_source": "node"
},
{
"cache_enabled": false,
"capability_id": "b8de3f88-b0cb-4a0b-a19a-81eb9b3e3ae5",
"default_timeout_seconds": 0,
"image_uri": "https://gitmoap.example/acme/bda0437b",
"node_id": "c592ff6c-69ae-44b3-8ac2-e46d4d0df670",
"provider_id": "8de81b43-6670-46e4-8f9d-5a06cb899b33",
"requires_docker": false,
"resolved_version": "resolved-version-7187",
"version_source": "node"
}
],
"valid": false,
"violations": [
{
"code": "provider_not_enabled",
"detail": "detail-e9aa",
"node_ids": [],
"provider_id": "6bdeedbc-c880-4ffc-9adb-6ea4613bf30d"
},
{
"code": "provider_not_enabled",
"detail": "detail-7cfb",
"node_ids": [],
"provider_id": "336cd460-1682-4096-ab6b-04e9b4c93884"
}
],
"warnings": [
{
"code": "provider_version_deprecated",
"detail": "detail-2afe",
"node_ids": [],
"provider_id": "3a583599-60c8-4aa7-9537-47f640a0a64a"
}
]
}
400application/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-a12f",
"message": "Pin a page's payload to the build that rendered it"
}
}
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-bbc1",
"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
  • 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-54cd",
"message": "Label every synthesized example"
}
}
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-a42b",
"message": "Pin a page's payload to the build that rendered it"
}
}
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-7540",
"message": "Pin a page's payload to the build that rendered it"
}
}

CLI

gitmoap pipeline-runs validate

  • --repo-ididRepository id (id or owner/repo path)
  • --resolved-dagjson

Used in these guides