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

Return a pipeline's definition with every component flattened into ordinary nodes

expand_pipeline
  • pipeline:read
    A token needs the pipeline:read scope: View pipeline runs and definitionsGranted by read_api, read_repository, write_api, write_repository.Every operation this scope unlocks

Resolves each component reference to its version and splices the component's nodes into the graph, returning the result, what each component contributed, and the diagnostics a save would report. Send a definition in the body to preview an unsaved edit instead of the stored pipeline; the pipeline you name must still exist. Nothing is written. Anyone who can read the repository's pipelines may call it; a draft can be expanded only by those who can manage pipelines (Maintainers and above), and to anyone else it is not found.

Parameters

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

Request body

application/json
  • definitionPipelineDefinitionInput or nulloptional
    • The PipelineDefinitionInput schema
    • namePipelineName (string)
    • component_instancesarray of ComponentInstanceoptionalComponents this pipeline uses. Each expands into ordinary steps and connections before the pipeline is validated.
      • The ComponentInstance schema
      • component_idComponentId (string · uuid)The component used, by id. Creating another component with the same name later never changes what this instance runs.
      • idNodeId (string)The instance's id, unique among the pipeline's step ids. Connections use it as they use a step id.
      • namestringDisplay name, also put in front of the display names of the steps it expands into.
      • versionComponentVersionRef (string)
      • component_refstring or nulloptionalThe reference as the author wrote it, kept for display. It is not used to find the component.
      • paramsobjectoptionalValues for the component's parameters, by parameter name.
      • stage_mapobjectoptionalMaps every stage slot the component declares to a stage of this pipeline, keeping the slots' order.
    • descriptionstring or nulloptional
    • edgesarray of Edgeoptional
      • The Edge schema
      • idEdgeId (string)
      • source_node_idNodeId (string)
      • target_node_idNodeId (string)
      • source_portPortName (string) or nulloptionalAbsent on a dependency-only edge.
      • target_portPortName (string) or nulloptionalAbsent on a dependency-only edge.
    • stagesarray of Stageoptional
      • The Stage schema
      • idStageId (string)
      • namestring
      • stage_typeStageTypesourcebuildtestpublishdeploynotifycustomThe pipeline stage a capability belongs to. Maps verbatim to the stage_type field of a capability in gitmoap-provider.yaml.
      • barrier_modeBarrierModestrictlenientoptionalWhen 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.
      • nodesarray of Nodeoptional
    • statusPipelineDefinitionStatusdraftpublishedor nulloptionalSave as a draft (problems reported, not runnable) or as published (must be valid, runnable). Defaults to published.
    • trigger_configTriggerConfigoptional
Request body exampleSynthesized example
{}

Responses

200The flattened graph, plus what each component contributed to it. Send a definition in the body to preview an unsaved edit instead of the stored oneapplication/json
  • definitionPipelineDefinitionInputThe flattened definition, with no component instances left in it.
    • The PipelineDefinitionInput schema
    • namePipelineName (string)
    • component_instancesarray of ComponentInstanceoptionalComponents this pipeline uses. Each expands into ordinary steps and connections before the pipeline is validated.
      • The ComponentInstance schema
      • component_idComponentId (string · uuid)The component used, by id. Creating another component with the same name later never changes what this instance runs.
      • idNodeId (string)The instance's id, unique among the pipeline's step ids. Connections use it as they use a step id.
      • namestringDisplay name, also put in front of the display names of the steps it expands into.
      • versionComponentVersionRef (string)
      • component_refstring or nulloptionalThe reference as the author wrote it, kept for display. It is not used to find the component.
      • paramsobjectoptionalValues for the component's parameters, by parameter name.
      • stage_mapobjectoptionalMaps every stage slot the component declares to a stage of this pipeline, keeping the slots' order.
    • descriptionstring or nulloptional
    • edgesarray of Edgeoptional
      • The Edge schema
      • idEdgeId (string)
      • source_node_idNodeId (string)
      • target_node_idNodeId (string)
      • source_portPortName (string) or nulloptionalAbsent on a dependency-only edge.
      • target_portPortName (string) or nulloptionalAbsent on a dependency-only edge.
    • stagesarray of Stageoptional
      • The Stage schema
      • idStageId (string)
      • namestring
      • stage_typeStageTypesourcebuildtestpublishdeploynotifycustomThe pipeline stage a capability belongs to. Maps verbatim to the stage_type field of a capability in gitmoap-provider.yaml.
      • barrier_modeBarrierModestrictlenientoptionalWhen 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.
      • nodesarray of Nodeoptional
    • statusPipelineDefinitionStatusdraftpublishedor nulloptionalSave as a draft (problems reported, not runnable) or as published (must be valid, runnable). Defaults to published.
    • trigger_configTriggerConfigoptional
  • diagnosticsValidationSummary
    • The ValidationSummary schema
    • validboolean
    • violationsarray of ValidationViolation
    • warningsarray of ValidationWarningoptionalThings worth knowing that do not make the definition invalid, such as a deprecated component version. A violation stops a published definition from being saved; a warning never does. Left out when there are none.
  • instancesarray of ExpandedInstanceInfo
    • The ExpandedInstanceInfo schema
    • component_idComponentId (string · uuid)
    • component_nameComponentName (string)
    • instance_idNodeId (string)
    • node_idsarray of NodeId (string)The identifiers expansion minted for this instance's nodes.
    • resolved_versionComponentVersion (string)
    • version_refComponentVersionRef (string)
200 exampleSynthesized example
{
"definition": {
"name": "payments-api",
"component_instances": [
{
"component_id": "7120bb99-5720-49e8-8550-e15af10a4171",
"id": "id-5d99",
"name": "payments-api",
"version": "version-eee7"
}
],
"description": "Renders each region as density contours of its operations.",
"edges": [
{
"id": "id-3e00",
"source_node_id": "c7e9dd86-79e2-4023-a391-0759c377b112",
"target_node_id": "a20438d9-5164-4c67-9dc5-1a9491e1d053"
}
],
"stages": [
{
"id": "id-462e",
"name": "payments-api",
"stage_type": "source"
},
{
"id": "id-78db",
"name": "payments-api",
"stage_type": "source"
}
],
"status": "draft",
"trigger_config": {
"events": [
{
"type": "push"
}
]
}
},
"diagnostics": {
"valid": false,
"violations": [
{
"code": "code-8127",
"message": "Stream pipeline status into the run header",
"target": {
"kind": "pipeline"
}
},
{
"code": "code-77ba",
"message": "Draw the region map from operation density",
"target": {
"kind": "pipeline"
}
}
],
"warnings": [
{
"code": "code-dc3c",
"message": "Stream pipeline status into the run header",
"target": {
"kind": "pipeline"
}
}
]
},
"instances": [
{
"component_id": "680ae119-6277-4be3-bad4-593b18df8e2b",
"component_name": "payments-api",
"instance_id": "b345489e-5925-44c8-a3cc-fb0ed8ae7b61",
"node_ids": [],
"resolved_version": "resolved-version-c1eb",
"version_ref": "version-ref-d460"
}
]
}
400The supplied definition is malformedapplication/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-d3db",
"message": "Label every synthesized example"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/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-94e2",
"message": "Inline scalar newtypes but keep their brand"
}
}
403Reporter is required to read a pipelineapplication/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-4aad",
"message": "Stream pipeline status into the run header"
}
}
404No such repository or pipeline, or the pipeline is a draft you cannot manageapplication/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-9ed4",
"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-dc91",
"message": "Draw the region map from operation density"
}
}

CLI

gitmoap pipelines expand

  • --repo-ididRepository id (id or owner/repo path)
  • --pipeline-ididPipeline definition id
  • --definitionjsonoptional

Used in these guides