aws apigateway create-deployment: Deploy an API Stage in CI

Publish a snapshot of a REST API to a named stage.

aws apigateway create-deployment takes the current REST API configuration and publishes it to a stage, making changes live. In CI it is the step that activates updated routes or integrations after they are defined, returning a deployment ID.

Common flags

--rest-api-id - the REST API ID (required)
--stage-name - the stage to deploy to (required, e.g. prod)
--description - label the deployment
--stage-description - description for a newly created stage

Example in CI

Publish the API to the prod stage.

shell

aws apigateway create-deployment --rest-api-id ${API_ID} --stage-name prod --description "ci deploy ${GITHUB_SHA}"

Common errors in CI

An error occurred (NotFoundException) - rest-api-id wrong or in another region
An error occurred (BadRequestException) - no integrations defined, nothing to deploy
An error occurred (AccessDeniedException) - role lacks apigateway:POST on /deployments
Note: this is for REST (v1) APIs; HTTP/WebSocket (v2) use apigatewayv2 with auto-deploy

Key takeaways

create-deployment makes the current REST API config live on a stage.
This is REST API v1; HTTP/WebSocket APIs use apigatewayv2 (often auto-deploy).
BadRequestException usually means there are no integrations to deploy.