Skip to content
GitmoapAPIBeta
Shipcatalog
GET/catalog/services/{service_id}/deployments/drift

How far behind its default branch each deployment is

get_service_deployment_drift
  • catalog:read
    A token needs the catalog:read scope: Read the service catalog: services, their bindings, their owners and their overviewsGranted by read_api, write_api.Every operation this scope unlocks

For each environment and repository where the service has a current deployment, counts the commits on the repository's default branch since the deployed commit. A service built from several repositories gets one answer per repository, never an average. A deployed commit that can no longer be read reports no count rather than failing the request, and a very long gap is flagged as cut short. Reporters and above may call it.

Parameters

Path
  • service_idServiceId (string · uuid)The service's id

Responses

200One entry per environment and repository with a current deployment, never averaged across repositoriesapplication/json
  • rowsarray of DeploymentDriftRow
    • The DeploymentDriftRow schema
    • default_branchstring
    • deployed_shastring
    • environmentEnvironmentSummary
      • The EnvironmentSummary schema
      • archivedboolean
      • environment_idEnvironmentId (string · uuid)
      • scopeScopeRef
      • slugEnvironmentSlug (string)
      • tierEnvironmentTierdevelopmenttestingstagingproductionWhat kind of environment this is, whatever it is called: development, testing, staging or production. A production environment is protected by default.
      • display_namestring or nulloptional
      • urlstring or nulloptional
    • repository_idRepositoryId (string · uuid)
    • repository_pathstring
    • commitsarray of DriftCommitoptionalThe commits the deployment is missing, at most 100. When there are more, truncated is true and commits_behind still gives the full count.
    • commits_behindinteger · int32 or nulloptional0–∞How many commits the default branch has that the deployed commit does not. Absent when the deployed commit can no longer be read, for example after a force-push.
    • truncatedbooleanoptional
  • service_idServiceId (string · uuid)
200 exampleSynthesized example
{
"rows": [
{
"default_branch": "main",
"deployed_sha": "a5ae076f09cec4520d7008bb97379b850541346e",
"environment": {
"archived": false,
"environment_id": "bc35d0dc-c7c5-486b-9730-8868354fa6d4",
"scope": {
"group": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69"
},
"slug": "slug-5d1b",
"tier": "development"
},
"repository_id": "5b0e7c2a-9d14-4e8b-a6f1-2c3d4e5f6a70",
"repository_path": "repository-path-d098"
}
],
"service_id": "eb4826de-1141-4951-9d48-1459cb3709b1"
}
400Bad request — a path parameter is not a well-formed value of its typeapplication/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-2cf2",
"message": "Stream pipeline status into the run header"
}
}
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-4a4e",
"message": "Stream pipeline status into the run header"
}
}
403Forbidden — the caller's access level or token scope is insufficientapplication/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-81e1",
"message": "Stream pipeline status into the run header"
}
}
404No such service, or it is not visible to the callerapplication/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-39c2",
"message": "Label every synthesized example"
}
}

CLI

gitmoap catalog get-service-deployment-drift

  • --service-ididThe service's id

Used in these guides