Skip to content
GitmoapAPIBeta
Buildpipeline-components
POST/repositories/{repo_id}/pipeline-components/{component_id}/repin

Move consuming pipelines onto a different version reference

repin_repo_component_usages
  • pipeline:manage
    A token needs the pipeline:manage scope: Create, update, and delete pipeline definitionsGranted by write_api, write_repository.Every operation this scope unlocks
  • Audited · mutation

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

  • Dry run
    Takes dry_run.

Rewrites the component reference in the pipelines that use it to the reference you name, optionally only where the old reference was written a given way or only in the pipelines you list. A pipeline is skipped, with the reason, when you cannot manage its repository or when the change would stop it validating: owning a component is not authority over the pipelines that use it. A reference no published version satisfies is refused outright. One call examines a bounded number of consumers and says when more remain; pass dry_run=true to see the outcome without writing. Maintainers and above on the component's scope.

Parameters

Path
  • repo_idRepositoryId (string · uuid)The repository's id
  • component_idComponentId (string · uuid)The component's id
Query
  • dry_runbooleanoptionalWork out what would change and write nothing

Request body

application/json
  • toComponentVersionRef (string)The reference every matched instance is rewritten to.
  • fromComponentVersionRef (string) or nulloptionalRewrite only instances whose reference is written exactly this way. Absent rewrites every reference to this component, floating ones included.
  • pipeline_idsarray of PipelineId (string · uuid) or nulloptionalRewrite only these pipelines. Absent means every pipeline that uses the component.
Request body exampleSynthesized example
{
"to": "to-e69c"
}

Responses

200Which pipelines moved and which were left alone, each with the reason. A pipeline is skipped rather than rewritten when you cannot manage its repository, or when the change would stop it validating — owning a component is not authority over the pipelines that use itapplication/json
  • candidatesinteger · int320–∞Consumers matching the filter that the sweep looked at, before authorization or validation.
  • dry_runbooleanTrue when nothing was written and the report describes what would have happened.
  • toComponentVersionRef (string)
  • repinnedarray of RepinnedPipelineoptional
  • skippedarray of RepinSkipoptional
    • The RepinSkip schema
    • pipeline_idPipelineId (string · uuid)
    • pipeline_namePipelineName (string)
    • reasonRepinSkipReasonforbiddenunreadablealready_pinnedvalidation_failedpipeline_missingWhy a re-pin left a pipeline unchanged: forbidden (you cannot manage its pipelines), unreadable (you cannot read its repository), already_pinned (it already uses the requested reference), validation_failed (the change would make it invalid) or pipeline_missing (the pipeline no longer exists).
    • repository_idRepositoryId (string · uuid)
    • detailstring or nulloptionalWhat went wrong, when the reason alone does not say. Carries the validation message for a pipeline that would stop validating.
  • truncatedbooleanoptionalTrue when the component has more consumers than one sweep examines. The remainder are reached by running the sweep again.
200 exampleSynthesized example
{
"candidates": 27,
"dry_run": false,
"to": "to-cd1a",
"repinned": [
{
"instances": [],
"pipeline_id": "160766b4-a119-49ec-8dbe-28441c00ae6b",
"pipeline_name": "payments-api",
"repository_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70"
},
{
"instances": [],
"pipeline_id": "edb20ea4-582b-4553-a519-e7afe1080c20",
"pipeline_name": "payments-api",
"repository_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70"
}
],
"skipped": [
{
"pipeline_id": "eca6cf6a-ddc0-481e-bd34-dccf8b5ea63f",
"pipeline_name": "payments-api",
"reason": "forbidden",
"repository_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70"
},
{
"pipeline_id": "2dc10899-66b6-48b0-8c79-79b707d8c39e",
"pipeline_name": "payments-api",
"reason": "forbidden",
"repository_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70"
}
],
"truncated": false
}
400Malformed request, or no published version satisfies the requested referenceapplication/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-d8b7",
"message": "Pin a page's payload to the build that rendered it"
}
}
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-5142",
"message": "Label every synthesized example"
}
}
403Maintainer is required to re-pin a component's consumersapplication/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-debb",
"message": "Label every synthesized example"
}
}
404No such component hereapplication/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-ac31",
"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-593c",
"message": "Draw the region map from operation density"
}
}

CLI

gitmoap pipeline-components repin-repo-component-usages

  • --repo-ididThe repository's id (id or owner/repo path)
  • --component-ididThe component's id
  • --dry-runflagoptionalWork out what would change and write nothing
  • --fromstringoptional
  • --pipeline-idsjsonoptionalRewrite only these pipelines. Absent means every pipeline that uses the component.
  • --tostringThe reference every matched instance is rewritten to.

Used in these guides