a month ago
Hello Railway team,
We are preparing a controlled precheck deployment with automatic retries disabled. Before executing it, we need clarification of the public API contract:
-
For serviceInstanceDeploy, at what point are startCommand, restartPolicy, healthcheck settings, ordinary service variables and reference variables bound to that deployment? If the request was accepted but its response was lost, can subsequent serviceInstanceUpdate / variable updates change the settings used by that already accepted deployment at build or startup?
-
If serviceInstanceDeploy was accepted but the caller did not receive a deployment id, is there a documented maximum delay before it becomes visible in the service/environment deployments query? If no bound exists, what read-only reconciliation mechanism can establish whether the request was accepted, so we can avoid both a duplicate deployment and prematurely restoring service configuration?
-
Deployment Actions says restarting a crashed deployment restores its original image and configuration. Does the same binding apply to automatic crash restarts and platform-initiated restarts, including runtime/reference variables, even if service settings have changed since the original deployment?
We understand that GraphQL errors/HTTP status do not provide exactly-once guarantees. We are asking about the platform contract, not asking you to trigger or change any deployment. Please point us to a documented guarantee or confirm where the outcome must remain unknown.
Thank you.
1 Replies
Status changed to Awaiting Railway Response Railway • 29 days ago
a month ago
This thread has been opened as a bounty so the community can help solve it.
Status changed to Open Railway • 29 days ago
a month ago
Hi - a documentation-based pass over your four questions. I don't work for Railway, so this isn't an official answer; I've flagged where the docs stay silent.
1) When are settings bound to a deployment, and can later updates change an already-accepted one?
Railway builds the service into a container and then "starts the service using either the detected or configured Start Command. This cycle represents a deployment in Railway."
Configuration edits are not applied in place: changes "will be staged in a changeset for you to review and apply", and deploying applies all of the changes at once ("Clicking 'Deploy' will deploy all of the changes at once. Any services that are affected will be redeployed.").
Reference variables also participate in deploy ordering: "When multiple services deploy together, Railway uses reference variables to determine the deploy order." A service that references another waits for it to finish deploying before it starts.
Practical reading: startCommand / restartPolicy / healthchecks / ordinary variables / reference variables bind at the deployment's creation/start. Nothing in the docs lets a post-acceptance serviceInstanceUpdate or variable update change an already-accepted deployment. So an accepted deploy whose response was lost should keep the snapshot it was created with.
2) Is there a documented maximum delay before the accepted deploy becomes visible in the deployments query?
No documented upper bound. The documented anchors:
- Acceptance: "Every Deployment in Railway begins as Initializing - once it has been accepted into Railway's build queue, the status will change to Building."
- Visibility: "All deployments will appear in the deployments view on your selected service."
So: accepted implies eventually visible, but no documented accept-to-visible latency guarantee.
3) Read-only reconciliation (avoid both a duplicate deploy and a premature config restore)
- Poll the service/environment deployments list (documented read surface) and match candidates on generated metadata: OTEL_SERVICE_VERSION is "the commit SHA of the deployment, or the deployment ID for image and CLI deployments"; RAILWAY_DEPLOYMENT_ID is "the ID for the deployment."
- Do not blind-retry: no idempotency key or exactly-once statement appears in the docs, and "not visible yet" is not "rejected." Reconcile first; retry only past a threshold you choose.
- Singleton deploys raise the stakes: "By default, Railway maintains only one deploy per service ... if you trigger a new deploy either manually or automatically, the old version will be stopped and removed" - a duplicate would supersede it.
- Do not apply other configuration while the accepted deployment is still Initializing/Building: staged edits accumulate; applying them triggers further redeploys.
- If polling programmatically, respect the documented API rate limits (e.g., 100 RPH Free / 1000 RPH Hobby) and use backoff.
4) Crash restarts and platform-initiated restarts
- Automatic restarts run under Restart Policy: "The default is On Failure with a maximum of 10 restarts"; "Railway automatically restarts crashed Deployments up to 10 times ... After this limit is reached, your deployment status is changed to Crashed."
- Crash-restart binding: "Restarting a crashed Deployment restores the exact image containing the code & configuration of the original build." Manual restarts follow the same model (the Command Palette can "restart a deployment at any state").
- Platform-initiated: the documented class is a new deployment, not a restart of the original snapshot - "Occasionally, Railway will initiate a new deployment to migrate your service from one host to another" (banner-marked; can repeat). A new deployment means current settings apply - semantics differ from a crash restart.
- The docs give no field-by-field binding table for runtime vs reference variables across restarts. If determinism matters, ask Railway here, or verify with a canary (record RAILWAY_DEPLOYMENT_ID / OTEL_SERVICE_VERSION before/after a crash restart).
On exactly-once: consistent with your understanding - no exactly-once guarantee; GraphQL errors and HTTP status are not transactional acknowledgements. Reconcile first (see 3).
Worth confirming with Railway in this thread: (a) any accept-to-visible bound and (b) reference-variable re-resolution behavior on crash restarts - the two spots the docs alone can't settle.
References: https://docs.railway.com/deployments/reference, https://docs.railway.com/deployments/deployment-actions, https://docs.railway.com/deployments/restart-policy, https://docs.railway.com/deployments/staged-changes, https://docs.railway.com/variables, https://docs.railway.com/variables/reference, https://docs.railway.com/reference/public-api