Environment Variables

How app env vars flow from GitHub secrets into Railway at deploy time.

Apps read environment variables from process.env.X in Railway at runtime. But your app's code, your GitHub repo, and your Railway service are three different places — so the tricky question is "how does a secret I store in GitHub end up in Railway?" This page maps the pipeline.

The Three Places

The deploy workflow bridges the three.

The Mapping File

Every app has a deploy.config.yml with a secrets: block. The left side is the variable name your app will see at runtime. The right side is the GitHub key name:

serviceId: "training-tracker"
rootDir: "apps/training-tracker"
secrets:
SLACK_BOT_TOKEN: "TRAINING_TRACKER_SLACK_BOT_TOKEN"
SLACK_WEBHOOK_URL: "TRAINING_TRACKER_SLACK_WEBHOOK_URL"
SLACK_CHANNEL: "TRAINING_TRACKER_SLACK_CHANNEL"
SLACK_SIGNING_SECRET: "TRAINING_TRACKER_SLACK_SIGNING_SECRET"

At runtime, process.env.SLACK_BOT_TOKEN in the training-tracker app reads the value stored in GitHub as TRAINING_TRACKER_SLACK_BOT_TOKEN.

The Per-App Workflow Passes the Value

Each app's staging/production workflow forwards GitHub values into the reusable deploy workflow:

secrets:
SLACK_BOT_TOKEN: ${{ secrets.TRAINING_TRACKER_SLACK_BOT_TOKEN }}
SLACK_WEBHOOK_URL: ${{ vars.TRAINING_TRACKER_SLACK_WEBHOOK_URL }}

• Use ${{ secrets.X }} for anything sensitive.
• Use ${{ vars.X }} for non-sensitive config (e.g. a channel name, a feature flag).

Naming Pattern

To keep GitHub variables collision-free across 30+ apps, prefix with the app name in snake_case:

{APP_NAME_SNAKE}_{VAR_NAME}

Examples: BREAKFAST_TRACKER_SLACK_WEBHOOK_URL, RECRUIT_ASHBY_API_KEY, STAFF_MEAL_TRACKER_OPENAI_API_KEY.

See Naming Conventions.

Adding a New Variable — Checklist

1. Add the GitHub key (in the correct environment — staging vs production) as a secret or var.
2. Add the mapping to apps/<your-app>/deploy.config.yml under secrets:.
3. Forward the value in both deploy-app-<app>-staging.yml and deploy-app-<app>-production.yml.
4. Trigger a deploy and confirm the variable appears in the Railway service environment.

Auto-Injected Variables (No Mapping Needed)

You don't declare these — the platform provides them:

• DATABASE_URL — from the environment's database service.
• AUTH_UI_URL — for every non-auth service.

Opt-In Services (Mapping Required)

File storage and notification email are shared by the platform, but they reach only the apps that ask for them. The values are set once in GitHub Environments. An app turns a service on by mapping its values under secrets: in deploy.config.yml and forwarding its one secret in both deploy workflows. The PR check fails when an app's code and its map disagree.

Example App (apps/example-app) uses both, so its deploy.config.yml shows the lines to copy.

Auth API secrets and variables (GitHub Environments)

Set on both staging and production before deploying Auth API. Used by deploy-auth-staging.yml / deploy-auth-production.yml:

RESEND_FROM_EMAIL is non-sensitive (a public From address) so store it as a Variable, not a Secret. If magic links fail silently, check Resend domain verification and that RESEND_FROM_EMAIL matches the verified domain.

See also Auth & Access.

App notification email (GitHub Environments)

Apps send notification email from their own sender on mail.<apex>, never from the sign-in sender on login.<apex>. The values live once in the GitHub Environments, and a deploy copies them only onto apps that send email:

An app that sends email maps all three in the secrets: block of its deploy.config.yml (for example APP_EMAIL_API_KEY: "APP_EMAIL_API_KEY"), and its deploy-app-<app>-staging.yml and deploy-app-<app>-production.yml forward the APP_EMAIL_API_KEY secret. The two variables need no forwarding. An app without the map never receives the key, and the PR check fails when an app's code and its map disagree.

Ask Claude

Troubleshooting

If you're not sure how to add a GitHub secret, check with a developer before proceeding.

Quiz