Skip to main content

Railway Integration

Align connects to Railway so your deploys become part of the delivery picture: when a service deploys, the entries that shipped in it advance to deployed, and deploy history, failures, and service health flow into release readiness and client-facing status reports.

Unlike a code host, Railway reports to Align through a webhook — you generate a unique webhook URL in Align and paste it into your Railway project. That URL is the whole connection; a Railway API token is optional.

What it does​

  • Deploys advance work. A successful production deploy matches the Align entries it shipped — by commit SHA and by ALN-id references in the branch, commit message, or service — and moves them to deployed (after an optional health check). Which Railway environment counts as production is set by your environment mapping.
  • Release readiness. Recent deploys and their outcomes feed each release's readiness verdict alongside blockers, approvals, and CI.
  • Deploy reporting. Align's reporting assistant (Max) builds sections from your Railway stream: deploy history, build/deploy failures, per-service health, and environment drift (environments seen deploying that aren't mapped).
  • Client-readable status. Raw deploy detail stays internal; health and "what shipped" roll up into plain language for client-facing surfaces.

Requirements​

  • An Align workspace at app.alignsoft.us.
  • Admin or Manager role in the Align organization you're connecting.
  • A Railway project you can edit (to add the webhook).

Installation​

  1. In Align, open Marketplace → Railway → Install and confirm. Railway is a first-party app; there's no API key to copy — the connection is the webhook URL you generate next.
  2. On the setup screen, click Generate webhook URL. Align creates a unique, secret URL and shows it once.
  3. Copy the webhook URL.
  4. In Railway, open your project → Settings → Webhooks, add a webhook, and paste the URL. (See Railway's webhook docs.)
  5. In each Align project's Settings → Environments tab, set the Railway environment name (and optionally service) for each environment. This mapping is what attributes deploys to the right project and marks which environment is production — without it, deploys arrive but show up nowhere.

That's the entire setup. The webhook URL both authenticates the incoming deploys and identifies your workspace.

Optional: a Railway API token​

You can add a Railway API token (Account Settings → Tokens; account or workspace tokens both work) during setup. It is only used to verify access at connect time and is not required — the deploy feed runs entirely over the webhook. If you provide one, Align stores it encrypted (AES-256-GCM) and shows only whether one is present. Leave it blank to run token-free.

Permissions and webhooks​

Railway does not sign its webhooks, so the secret is the capability token embedded in your webhook URL. Treat the URL like a password. You can rotate it any time from Marketplace → Installed Apps → Railway — the previous URL stops working immediately, so update Railway afterwards.

Align only receives deploy events; it never writes to your Railway resources. If you added the optional token, it is used solely for the one-time access check and can be removed later without affecting the deploy feed.

Environment mapping​

Attribution is driven entirely by each project's Settings → Environments mapping:

  • Set Railway environment name to the exact environment Railway reports (e.g. production).
  • Optionally set a service to scope the mapping to one service.
  • Mark which environment is production — production deploys are the ones that advance entries to deployed.

The Railway configuration card in Installed Apps warns when no project has a Railway mapping yet, which is the usual reason a freshly-connected integration looks silent.

Uninstalling​

Disconnect from Marketplace → Installed Apps → Railway → Uninstall. Processing stops immediately — any further webhook calls from Railway are rejected. Remove the webhook from your Railway project's settings as well. Historical deploy events already recorded in Align remain, since they reference your own entries and releases.

Support​

Questions or issues: hello@send.alignsoft.us. We aim to respond within one business day.

Changelog​

  • 2026-07 — Webhook-first setup with an optional API token; deploys advance matched entries to deployed, feed release readiness, and power deploy-history / failure / service-health / env-drift reporting.