Skip to main content

Railway Integration

Align connects to Railway so your deploys move the entries they shipped and show up in Align's deploy reporting. Railway is a first-party Marketplace app: you install it, Align gives you a webhook URL, and you paste that URL into your Railway project. The URL is the whole connection; a Railway API token is optional.

What it does​

  • Deploys move entries. A successful deploy is matched to your projects through their environment mapping, then to the entries it carried: by commit SHA, and by ALN- references in the branch, commit message, or service and project names. A production deploy can move entries to Deployed; a testing or staging deploy moves them to Testing. The rules are the same as for GitHub deployments; see What moves entries.
  • Deployment stage. Each deploy records the stage (testing, staging or production) on the entries it carried. A release's readiness strip shows these as pipeline lamps.
  • Deploy reporting. Max, Align's assistant, can build report sections from your Railway deploys: deploy history and rollbacks, build and deploy failures, service health, and environment drift (environments seen deploying that aren't mapped). See Max.

Align only receives deploy events. It never writes to your Railway resources.

Requirements​

  • An Align workspace at app.alignsoft.us.
  • The Admin role in that workspace.
  • A Railway project you can edit, to add the webhook.

Installation​

  1. In Align, go to Settings → Integrations and click Install via Marketplace on the Railway row. (Or open Marketplace and choose Railway.)
  2. Click Install and confirm. There is no API key to copy.
  3. The Connect Railway dialog opens. Click Generate webhook URL. Align creates a unique, secret URL and shows it once.
  4. Copy the webhook URL.
  5. In Railway, open your project → Settings → Webhooks, add a webhook, and paste the URL. (See Railway's webhook docs.)
  6. Map your environments: in each Align project's Environments tab, set the Railway environment name for each environment. Without a mapping, deploys arrive but show up nowhere.

The webhook URL both authenticates the incoming deploys and identifies your workspace.

After installation, the Railway row in Settings → Integrations shows a status badge and a Manage button, which opens the installed app. Its Configuration section shows the state of the API token and the webhook, and warns when no project environment is mapped to Railway yet.

Optional: a Railway API token​

In the Connect Railway dialog you can add a Railway API token (Railway → Account Settings → Tokens; workspace tokens are supported) and an Account or team slug. The token is used only to verify access at setup; the deploy feed runs entirely over the webhook. Align stores it encrypted (AES-256-GCM) and shows only whether one is present. Entering a new token replaces the stored one and rotates the webhook URL.

Without a token, the badge on the Railway row in Settings → Integrations reads Needs credentials, even when the webhook is working. The installed app's Configuration section shows the real state of the webhook.

Environment mapping​

Attribution is driven by each project's Environments tab. For each environment:

  • Name: the name used in Align, for example "Testing".
  • Railway environment name: the environment name Railway reports, for example production.
  • Service name: optional. A deploy also matches the environment when its Railway service name matches this.
  • Production: marks the production environment. Only production deploys move entries to Deployed. Deploys to any other mapped environment move entries to Testing.
  • Advance entries on deploy: on unless you turn it off. When off, deploys to this environment are recorded but do not change entry statuses.
  • Notify on advance: sends a notification when a deploy moves an entry to Deployed.

Click Save after changing environments.

Permissions and webhooks​

Railway does not sign its webhooks, so the secret is the token embedded in your webhook URL. Treat the URL like a password. To rotate it, open Marketplace → Installed Apps → Railway and click Rotate webhook token. The previous URL stops working immediately, so update Railway afterwards.

If you added the optional token, it is used solely for the access check and can be removed later without affecting the deploy feed.

Uninstalling​

Open Marketplace → Installed Apps → Railway and, under Danger Zone, cancel the installation. Processing stops immediately: Align rejects further webhook calls from Railway. Remove the webhook from your Railway project's settings as well. Deploy events already recorded in Align remain.

Support​

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

Changelog​

  • 2026-10 — Support questions now go to support@alignsoft.us.
  • 2026-10 — Testing and staging deploys move the entries they carry to Testing; production deploys move closed entries to Deployed.
  • 2026-07 — Webhook-first setup with an optional API token; deploys advance matched entries and power deploy-history, failure, service-health and environment-drift reporting.