From e17cda9f79710cf52dcd41d97d50559d9cd763c1 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Mon, 20 Jul 2026 14:23:58 +0800 Subject: [PATCH 1/2] docs: document Railway CLI tokens in .env.example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the two Railway CLI credentials and where they belong, so remote agents and CI can authenticate without an interactive browser login. Both keys ship commented out — neither the Next.js app nor the worker reads them (src/lib/env.ts never references either), so this changes no runtime behaviour. - RAILWAY_TOKEN: project token, scoped to one project + environment. Preferred for CI; narrowest blast radius. - RAILWAY_API_TOKEN: account/workspace token, spans all projects. Required for account-level actions (railway list/link, GraphQL Public API). Also notes why ~/.railway/config.json must not be copied or committed: it holds a ~1h OAuth session plus absolute local worktree paths, so it is not portable. Points at the AGENTS.md provider-confirmation boundary and docs/worker-deploy-runbook.md, since deploys remain operator-confirmed. Co-Authored-By: Claude Opus 4.8 --- .env.example | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.env.example b/.env.example index ef70ac855..841dd9d15 100644 --- a/.env.example +++ b/.env.example @@ -182,3 +182,34 @@ WORKER_MEDSPACY_ASSERTION=false PYTHON_BIN=python # Optional when Tesseract is installed outside PATH on Windows. TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe + +# Railway deployment credentials (CI / remote agents only) +# NOT read by the Next.js app or the worker. src/lib/env.ts never references +# these; they exist purely so the Railway CLI can authenticate without an +# interactive browser login. Leaving them unset locally is correct and expected. +# +# Locally, `railway login` writes a short-lived OAuth session to +# ~/.railway/config.json (access token expires after ~1 hour, refreshed from the +# browser session). That file is machine-local and NOT portable: it also stores +# absolute Windows worktree paths. Never copy it to a remote machine or commit +# it — mint a real token below instead. +# +# Create tokens at: Railway dashboard -> Account Settings -> Tokens +# RAILWAY_TOKEN Project token. Scoped to ONE project + environment. +# Use for deploys/redeploys/logs. Preferred for CI — +# narrowest blast radius. Example: RAILWAY_TOKEN=xxx railway up +# RAILWAY_API_TOKEN Account/workspace token. Spans all projects and is +# required for account-level actions (railway list, +# railway link, GraphQL Public API). Broader access — only +# use when a project token genuinely cannot do the job. +# +# Store the value in a secret store, never in this repo: +# GitHub Actions gh secret set RAILWAY_TOKEN (read as ${{ secrets.RAILWAY_TOKEN }}) +# Cursor Cloud add as a Cloud Agent Secret (injected into process.env) +# Remote shell export RAILWAY_TOKEN=... (CLI prefers it over config.json) +# +# Rotate immediately if a token is ever pasted into a chat, log, PR, or commit. +# Deploys remain an operator-confirmed action in this repo — see AGENTS.md +# "API and provider confirmation boundary" and docs/worker-deploy-runbook.md. +#RAILWAY_TOKEN= +#RAILWAY_API_TOKEN= From afad5ee3d7ef783ef474705b3cf7d00b94397cd7 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Mon, 20 Jul 2026 14:31:10 +0800 Subject: [PATCH 2/2] docs: correct Railway token creation locations Addresses CodeRabbit review on #956. The original block sent readers to Account Settings for both tokens, which is wrong for the project token. Verified against Railway's Public API docs (/integrations/api): - Project token is created in Project Settings -> Tokens, scoped to one environment in one project. - Account and workspace tokens are created at railway.com/account/tokens; selecting a workspace scopes it, "No workspace" gives full account scope. These are two distinct types, not one. - Note that only one of RAILWAY_TOKEN / RAILWAY_API_TOKEN should be set. - Note the differing GraphQL headers (Project-Access-Token vs Authorization: Bearer) for direct API use. Co-Authored-By: Claude Opus 4.8 --- .env.example | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/.env.example b/.env.example index 841dd9d15..94c742401 100644 --- a/.env.example +++ b/.env.example @@ -194,14 +194,23 @@ TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe # absolute Windows worktree paths. Never copy it to a remote machine or commit # it — mint a real token below instead. # -# Create tokens at: Railway dashboard -> Account Settings -> Tokens -# RAILWAY_TOKEN Project token. Scoped to ONE project + environment. +# Railway has three token types. They are created in DIFFERENT places: +# RAILWAY_TOKEN Project token. Scoped to ONE environment in ONE project. +# Created in Project Settings -> Tokens (NOT account settings). # Use for deploys/redeploys/logs. Preferred for CI — # narrowest blast radius. Example: RAILWAY_TOKEN=xxx railway up -# RAILWAY_API_TOKEN Account/workspace token. Spans all projects and is -# required for account-level actions (railway list, -# railway link, GraphQL Public API). Broader access — only -# use when a project token genuinely cannot do the job. +# RAILWAY_API_TOKEN Account OR workspace token. Created at +# https://railway.com/account/tokens — pick a workspace to +# scope it to that workspace, or "No workspace" for a +# full-account token (broadest scope; do not share). +# Required for account-level actions (railway list, +# railway link). Prefer a workspace token over an account +# token, and only use either when a project token cannot +# do the job. +# Set only ONE of these at a time — they select different auth paths. +# Direct GraphQL Public API calls (not the CLI) differ too: project tokens use +# the `Project-Access-Token` header, account/workspace tokens use +# `Authorization: Bearer`. # # Store the value in a secret store, never in this repo: # GitHub Actions gh secret set RAILWAY_TOKEN (read as ${{ secrets.RAILWAY_TOKEN }})