Skip to content
Staircase

Deploy

Deploying any bundle to any environment, with retry, skip-if-unchanged, and completion reported to the health surface.

A deployment takes a bundle and an environment. It retries on transient failure, cancels cleanly when the platform's code-storage limit is reached rather than half-deploying, and skips entirely when the commit already deployed there.

Completion reports to Health, so the record of what is where is a consequence of deploying rather than a separate bookkeeping step.

How it works

The skip is keyed on the commit rather than on a version string. A version can be re-tagged; a commit cannot, so the check answers the actual question — is this exact code already running here.

Operations

Foo

POST /hello-world

Bar

helloWorld

Hello World

Dummy hello world endpoint

Response 200application/json
1 fields

Ok.

FieldTypeDescription
messagestringFooExample Hello, World!

Deployments

POST /deployments

Deploy Artifact

deployArtifact

Deploy Artifact

Deploy Artifact deploys a product or configuration artifact_url to a specific environment using only environment token from Environment product to provide information about the environment which is the final target of the deployment.

Limitations on Deployment
  • Deployment which handled by lambda worker supports up to 3 GB artifact size.
  • Deployment retries deployment up to 5 times if Deployer receives service error or throttling error.
  • Deployer will cancel deployment if lambda code storage hit %99 percent. The code storage percentage cache TTL is 10 minutes.
Legacy deployment
  • By default, the Deploy uses the new deployment strategy via StepFunctions. If you want to use the legacy deployment strategy via CodeBuild, you can enable it by passing legacy_deploy as true in the request body.
  • The legacy deployment strategy is deprecated and will be removed in the future.
  • The legacy deployment strategy is slower than the new deployment strategy.
Force Deployment

Deployer skips product deployment based on the following conditions:

Show the rest
  • The Last deployment should be successful.
  • The last deployment commit SHA should match the current bundle commit SHA. This indicates there is no code change in the given bundle.

Note: This behavior does not apply to configuration bundles. Configuration bundle deployments will be executed on every attempt.

This behavior can be changed by forcing the Deployer to execute deployment with the following options:

  1. Updating service.yml
deployment:
 force_deployment: true
  1. Giving force_deployment parameter in the request body.

Note: Parameter in request body overrides service.yml configuration. The deployment process will report to the Health after deployment finished or failed. The following health metric parameters will be sent: product_identifier: Taken from product_identifier field in the frontend bundles. Support for other bundles coming soon. product_api_identifier: always be5bed79-df72-4a56-b77c-5c12d4e21d8e status: "SUCCEEDED" or "FAILED" The deployment accepts optional parameter for transaction ID. If not provided, the deployment will create the transaction for the deployment.. The deployment process will persist following data into collection: Deployment status, Failed or Succeeded. Start time and end time of deployment. Bundle type of the deployment. Service, Chat, FrontEnd, Data.

Example of the collection:

{
 "metadata": {
 "fuzzy_searchable": false,
 "version": 3,
 "validation": true,
 "serialise_to_graph": true
 },
 "data": {
 "bundles": [
 {
 "@type": "bundle",
 "@id": "bundle_id",
 "bundle_type": "Service",
 "base_path": "your-base-path",
 "has_product": "p_id"
 }
 ],
 "products": [
 {
 "@id": "p_id",
 "@type": "product",
 "name": "MyProductName"
 },
 {
 "@id": "p_id_2",
 "@type": "product",
 "name": "Deploy",
 "product_identifier": "229c0982-b5fe-4d4c-8f9e-80ad38f5d4b8",
 "has_product_api": "product_api_id"
 }
 ],
 "deployments": [
 {
 "deployment_status_type": "Succeeded",
 "@type": "deployment",
 "@id": "depl_id",
 "has_invocation": "inv_id",
 "has_bundle": "bundle_id",
 "start_time": "2024-05-16T05:41:07.868339-04:00",
 "end_time": "2024-05-16T05:41:07.868339-04:00"
 }
 ],
 "product_apis": [
 {
 "@type": "product_api",
 "@id": "product_api_id",
 "name": "Deployment",
 "product_api_identifier": "a1257a35-5261-4293-9747-2e958c56f53c"
 }
 ],
 "invocations": [
 {
 "@type": "invocation",
 "invocation_message": "my-deployment-id",
 "@id": "inv_id",
 "has_product_api": "product_api_id"
 }
 ]
 }
}
Request
application/json 
{
  "bundle_id": "e00feb67-f6d7-46e4-95a-52375ece86ef",
  "transaction_id": "01HY0C4V3JS796NF9FXWDDNXT4",
  "artifacts_url": "https://example.com/artifact.zip",
  "environment_token": "rWiaN6NN6l0RPrrmM6he3QABhqCAAAAAAGBkJt205xbT9RPaH4kyB2JcGic4f-8vjZCIU7NZE8hVE2Trw6gqsDm0V7OMqST--jJUM3ri24BvyRYrI2EolmyWWKPNGlpVaA7",
  "callback_url": "https://example.com/call-me-back-please"
}
Response
application/json

Deployment started.

{
  "deploy_id": "devops-deployer-dev:490f5d55-2ea4-47b5-81cb-38a54a01f2af",
  "bundle_id": "e00feb67-f6d7-46e4-95a-52375ece86ef",
  "transaction_id": "01HY0C4V3JS796NF9FXWDDNXT4"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
Request bodyapplication/json
9 fields
FieldTypeDescription
transaction_idstringValid transaction ID from the Persistence product.
bundle_idstring (uuid)Any UUID.
environment_tokenrequiredstringToken from Environment product.
artifacts_urlrequiredstring (uri)Link to the artifacts zip file. Content of artifacts file described in Artifacts content section. Deployer will download artifacts from artifacts_url, and deploy them.Example https://example.com/artifact.zip
callback_urlstring (uri)(Optional) When deployment is done, POST to this API information about deployment. If a transient error is returned from callback deploy will retry 10 times to call callback using exponential back off algorithm. Transient error means either: a timeout, an FTP 5xx response code or an HTTP 5xx response code.Example https://example.com/call-me-back-please
log_levelstringLog level, that is used in deployment process. Can be used with \"DEBUG\" value for Deploy product debugging.DEBUGINFOExample INFO
force_deploymentbooleanThis allows Deployer to force execute deployment.Example true
legacy_deploybooleanUse legacy deployment strategy via CodeBuild. This option is deprecated and will be removed in the future.Example false
configurationobjectThis option configures deployment and is only effective when legacy_deploy disabled.
limit_check_on_pre_deploymentstringEnables AWS quota and limit check before deployment.Example true
parallel_module_deploymentstringAllows configuring parallel or sequential module deployment. Sequential deployment is important when module deployment order matters. This option is valid only for legacy_deploy deployment disabled.Example true
Response 200application/json
3 fields

Deployment started.

FieldTypeDescription
deploy_idstringID of the deployment.Example devops-deployer-dev:490f5d55-2ea4-47b5-81cb-38a54a01f2af
bundle_idstring (uuid)Usually a hash of the commit but can be any UUID.
transaction_idstringThe transaction ID.
Response 400application/json
2 fields

Parameter validation error

FieldTypeDescription
artifacts_urlstring[]Artifact URL errors
environment_tokenstring[]Environment token errors
Response 403application/json
1 fields

Forbidden

FieldTypeDescription
messagestringError message
Other responses

422

GET /deployments/{bundle_id}

Retrieve Deployment Status

retrieveDeploymentStatus

Retrieve Deployment Metadata retrieves metadata generated by the deployment.

  • Metadata is available only for deployments that succeed (deploy_status==SUCCEEDED).
  • The artifact_url key in the response body contains the URL to the artifact that was deployed. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
  • The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
Response
application/json

200 response

{
  "deploy_status": "SUCCEEDED",
  "metadata": {
    "target_url": "https://sandbox.api.staircaseapi.com/code-assessor/",
    "code": {
      "id": "4ad1c152-4990-45b4-a2ab-f0d31d1fc303",
      "timestamp": 1611753194.053118,
      "version": "1.1",
      "status": "SUCCEEDED",
      "commit_hash": "31e47b3e883cec9c46c435d57c58565e1f73b3a8",
      "issuer": "https://deploy.staircaseapi.com/code"
    },
    "builder": {
      "id": "f128507e-21c1-4dd8-b6bc-7bb0d220eeb8",
      "timestamp": 1611753314.9771907,
      "version": "1.1",
      "status": "SUCCEEDED",
      "issuer": "https://api.staircaseapi.com/infra-builder"
    },
    "deployer": {
      "id": "032e2794-7aa8-4e3a-912b-605f5c370913",
      "timestamp": 1611753374.9128177,
      "version": "1.1",
      "status": "SUCCEEDED",
      "issuer": "https://deploy.staircaseapi.com/infra-deployer/"
    }
  },
  "artifact_url": "https://deployer-dev-artifcatsbucket-1freahxorpmya.s3.amazonaws.com/build_artifacts/00c5f4ab-d3d4-4cd9-bc9d-eefe8b6b1c26/devops-deployer-dev/artifacts.zip?AWSAccessKeyId=<redacted>&Signature=<redacted>&Expires=1611832432",
  "logs": [
    "[Container] 2020/12/14 16:24:03 Waiting for agent ping\n",
    "[Container] 2020/12/14 16:24:05 Waiting for DOWNLOAD_SOURCE\n",
    "[Container] 2020/12/14 16:24:06 Phase is DOWNLOAD_SOURCE\n",
    "[Container] 2020/12/14 16:24:06 CODEBUILD_SRC_DIR=/codebuild/output/src405111012/src\n",
    "[Container] 2020/12/14 16:24:06 YAML location is /codebuild/readonly/buildspec.yml\n",
    "[Container] 2020/12/14 16:24:06 No commands found for phase name: install\n",
    "[Container] 2020/12/14 16:24:06 Processing environment variables\n",
    "[Container] 2020/12/14 16:24:06 Selecting 'python' runtime version '3.8' based on manual selections...\n",
    "[Container] 2020/12/14 16:24:06 Running command echo \"Installing Python version 3.8 ...\"\n",
    "Installing Python version 3.8 ...\n",
    "\n",
    "[Container] 2020/12/14 16:24:06 Running command pyenv global  $PYTHON_38_VERSION\n",
    "\n",
    "[Container] 2020/12/14 16:24:07 Moving to directory /codebuild/output/src405111012/src\n",
    "[Container] 2020/12/14 16:24:07 Registering with agent\n",
    "[Container] 2020/12/14 16:24:07 Phases found in YAML: 2\n",
    "[Container] 2020/12/14 16:24:07  INSTALL: 0 commands\n",
    "[Container] 2020/12/14 16:24:07  BUILD: 6 commands\n",
    "[Container] 2020/12/14 16:24:07 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:24:07 Phase context status code:  Message:\n",
    "[Container] 2020/12/14 16:24:07 Entering phase INSTALL\n",
    "[Container] 2020/12/14 16:24:07 Phase complete: INSTALL State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:24:07 Phase context status code:  Message:\n",
    "[Container] 2020/12/14 16:24:07 Entering phase PRE_BUILD\n",
    "[Container] 2020/12/14 16:24:07 Phase complete: PRE_BUILD State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:24:07 Phase context status code:  Message:\n",
    "[Container] 2020/12/14 16:24:07 Entering phase BUILD\n",
    "[Container] 2020/12/14 16:24:07 Running command curl -sS \"\"$HOST\"infra-deployer/deploy.py\" --output deploy.py\n",
    "\n",
    "[Container] 2020/12/14 16:24:10 Running command curl -sS $ARTIFACTS_URL --output artifacts.zip\n",
    "\n",
    "[Container] 2020/12/14 16:24:11 Running command unzip -qq artifacts.zip -d build_folder\n",
    "\n",
    "[Container] 2020/12/14 16:24:11 Running command printf \"$ACCESS_KEY\\n$SECRET_KEY\\nus-east-1\\njson\" > creds.txt\n",
    "\n",
    "[Container] 2020/12/14 16:24:11 Running command aws configure < creds.txt\n",
    "AWS Access Key ID [None]: AWS Secret Access Key [None]: Default region name [None]: Default output format [None]:\n",
    "[Container] 2020/12/14 16:24:16 Running command python3.8 deploy.py build_folder\n",
    "2020-12-14 16:24:17,684 Found credentials in shared credentials file: ~/.aws/credentials\n",
    "2020-12-14 16:24:18,007 Creating bucket 2b7d31ed-7ff3-4da8-9ad9-324f40bf41a0\n",
    "2020-12-14 16:24:18,323 Bucket created\n",
    "2020-12-14 16:24:18,324 Uploading artifacts\n",
    "2020-12-14 16:24:18,574 Artifacts uploaded\n",
    "2020-12-14 16:24:18,574 Deployment started\n",
    "2020-12-14 16:25:30,449 Deployed\n",
    "2020-12-14 16:25:30,449 Removing bucket 2b7d31ed-7ff3-4da8-9ad9-324f40bf41a0\n",
    "2020-12-14 16:25:31,128 Bucket removed\n",
    "\n",
    "[Container] 2020/12/14 16:25:31 Running command if [ \"$CALLBACK_URL\" != \"null\" ]; then\n",
    "\n  if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then\n",
    "\n    curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
    "\n  else\n",
    "\n    curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
    "\n  fi\n",
    "fi\n",
    "",
    "\n  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
    "\n                                 Dload  Upload   Total   Spent    Left  Speed\n",
    "\r  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r100    75    0     0  100    75      0    247 --:--:-- --:--:-- --:--:--   246\n",
    "\n",
    "[Container] 2020/12/14 16:25:31 Phase complete: BUILD State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:25:31 Phase context status code:  Message:\n",
    "[Container] 2020/12/14 16:25:31 Entering phase POST_BUILD\n",
    "[Container] 2020/12/14 16:25:31 Phase complete: POST_BUILD State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:25:31 Phase context status code:  Message:\n",
    "[Container] 2020/12/14 16:25:31 Expanding base directory path: .\n",
    "[Container] 2020/12/14 16:25:31 Assembling file list\n",
    "[Container] 2020/12/14 16:25:31 Expanding .\n",
    "[Container] 2020/12/14 16:25:31 Expanding file paths for base directory .\n",
    "[Container] 2020/12/14 16:25:31 Assembling file list\n",
    "[Container] 2020/12/14 16:25:31 Expanding deploy_output.json\n",
    "[Container] 2020/12/14 16:25:31 Found 1 file(s)\n",
    "[Container] 2020/12/14 16:25:31 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
    "[Container] 2020/12/14 16:25:31 Phase context status code:  Message:\n"
  ]
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
bundle_id required string (uuid) path e00feb67-f6d7-46e4-95a-52375ece86ef Usually a hash of the commit but can be any UUID.
Response 200application/json
5 fields

200 response

FieldTypeDescription
deploy_statusstringDeploy status can be SUCCEEDED'|'FAILED'|'FAULT'|'TIMED_OUT'|'IN_PROGRESS'|'STOPPED.FAILEDFAULTIN_PROGRESSSTOPPEDSUCCEEDEDTIMED_OUT
metadataobjectMetadata
target_urlstring (uri)Target URLExample https://sandbox.api.staircaseapi.com/code-assessor/
artifact_urlstring (uri)URL of deployed artifact, with proper metadata in headers.
logsstring[]Logs of deployment.
bundle_detailsobject[]Bundle deployment details
Response 403application/json
1 fields

Forbidden

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found

FieldTypeDescription
messagestringError message
Response 409application/json
1 fields

Request could not be processed because of conflict in the current state of the resource

FieldTypeDescription
messagestringError message
Other responses

400422

GET /deployments/logs/{response_collection_id}

Retrieve Deployment Logs

retrieveDeploymentLogs

Retrieve Deployment Logs retrieves logs and stack traces if an exception occurred during deployment. This endpoint is reachable with an API key and health key.

Limitations:

  • Logs have 7 days TTL.
Response
application/json

200 response

[
  {
    "response_collection_id": "225b1744-2b9f-4861-b8b5-55bf4dd0726f",
    "product_api_identifier": "11225b1744-239f-4861-b8b5-55bf4dd072",
    "transaction_id": "fb27c142-5421-4f51-8a5d-bb5078e6e7c6",
    "stack_trace": "stack_trace_value",
    "created_at": "2022-12-01:07:23:07",
    "expire_at": 1670484187
  }
]
Parameters
3
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
response_collection_id required string (uuid) path e00feb67-f6d7-46e4-95a-52375ece86ef The value of response collection_id.
product_api_identifier string query 11225b1744-239f-4861-b8b5-55bf4dd072 Product API identifier
Response 200application/json
6 fields

200 response

FieldTypeDescription
response_collection_idstringResponse collection identifier.
product_api_identifierstringProduct API identifier.
transaction_idstringTransaction identifier
stack_tracestringExecution stack trace
created_atstringLog creation date.
expire_atnumberLog expiration specifier.
Response 403application/json
1 fields

Forbidden

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found

FieldTypeDescription
messagestringError message
Response 409application/json
1 fields

Request could not be processed because of conflict in the current state of the resource

FieldTypeDescription
messagestringError message
Other responses

400422

Operations

GET /deployments/{deployId}

Get deploy status

Getdeploy

Parameters
1
ParameterTypeDescription
deployId required string path ID of deploy, looks like 5f0631cd1487f8000897e143
Other responses

200

POST /deploymentStrategies/blue-green/execute

Redeploy

Redeploy

Request
application/json 
{
  "applicationName": "app",
  "oldDeployId": "5efb0e03b61e2500082c8292",
  "revisionLocation": "s3://staircase-poc/GreenDeploy_Linux.zip"
}
Request bodyapplication/json
3 fields
FieldTypeDescription
applicationNamerequiredstring—
oldDeployIdrequiredstring—
revisionLocationrequiredstring—
Other responses

200

Errors

400403404409422

Type to search.