railway-project-management

This skill provides complete workflows for:

• Creating and linking Railway projects
• Managing environments (production, staging, PR environments)
• Adding services from GitHub, Docker, or local sources
• Configuring variables (service, shared, reference, sealed)
• Syncing and duplicating environments
• Project settings and validation

• Railway CLI installed and authenticated (use railway-auth skill)
• Git repository (for GitHub integrations)
• Docker (optional, for container deployments)

1. Project Creation and Linking

Create new Railway project:

```bash

# Initialize new project interactively

railway init

# Create project with specific name

railway init --name "my-project"

# Link to existing project (interactive)

railway link

# Link to specific project by ID

railway link -p

# Link to project with specific environment and service

railway link -p -e -s

# Check current project status

railway status

```

Project information:

```bash

# View project details

railway status

# View project in browser

railway open

# Unlink from current project

railway unlink

```

2. Environment Management

Create and switch environments:

```bash

# List all environments

railway environment

# Create new empty environment

railway environment --name staging

# Create duplicate of current environment

railway environment --name production-backup --duplicate

# Switch to specific environment

railway environment production

# Delete environment (interactive)

railway environment delete

```

Environment types:

• Production: Main deployment environment
• Staging: Pre-production testing
• PR Environments: Auto-created per pull request
• Custom: Any named environment for specific needs

See references/environment-types.md for detailed guide.

3. Service Operations

Add services from different sources:

```bash

# Add service from GitHub repository

railway add --repo owner/repo

# Add service from current directory

railway add

# Add Docker image

railway add --image postgres:15

# Add template (e.g., database)

railway add --template postgres

```

Service sources:

• GitHub: Auto-deploy from repository
• Docker: Deploy container images
• Local: Deploy from current directory
• Templates: Pre-configured services (databases, etc.)

See references/service-sources.md for detailed configurations.

4. Variable Management

Set variables at different scopes:

```bash

# Set service variable (current service only)

railway variables set API_KEY=secret123

# Set shared variable (all services in environment)

railway variables set --shared DATABASE_URL=postgres://...

# Set sealed variable (enhanced security)

railway variables set --sealed STRIPE_KEY=sk_live_...

# Reference variable from another service

railway variables set API_URL='${{ api-service.PUBLIC_URL }}'

# Delete variable

railway variables delete API_KEY

# List all variables

railway variables list

```

Variable types:

1. Service Variables: Isolated to specific service
2. Shared Variables: Available to all services in environment
3. Reference Variables: Reference other service variables using ${{ service.VAR }} syntax
4. Sealed Variables: Enhanced security, cannot be unsealed or viewed after creation

Variable scoping:

```

Project

├── Environment (production)

│ ├── Service A

│ │ ├── Service variables (API_KEY)

│ │ └── Can access shared variables

│ ├── Service B

│ │ ├── Service variables (DB_PASSWORD)

│ │ └── Can access shared variables

│ └── Shared variables (LOG_LEVEL, NODE_ENV)

```

See references/variable-scoping.md for advanced patterns.

5. Configuration and Settings

Project settings:

```bash

# View project settings in browser

railway open --settings

# Enable/configure PR environments

# (Done via dashboard - automated per PR)

# Configure deployment triggers

# (Done via dashboard - branch filters, paths)

```

Service settings:

```bash

# View service in browser

railway open

# Configure via railway.json or railway.toml

cat > railway.json <

{

"build": {

"builder": "NIXPACKS",

"buildCommand": "npm run build"

},

"deploy": {

"startCommand": "npm start",

"healthcheckPath": "/health",

"restartPolicyType": "ON_FAILURE"

}

}

EOF

```

Advanced configuration:

• Health checks and restart policies
• Resource limits (CPU, memory)
• Custom build commands
• Root directory overrides
• Networking and domains

6. Verification and Validation

Verify project setup:

```bash

# Check project status

railway status

# List all environments

railway environment

# List services

railway list

# Check variables

railway variables list

# View logs

railway logs

# Open in browser for visual verification

railway open

```

Common validation checks:

• ✅ Project linked correctly
• ✅ Environments created (production, staging)
• ✅ Services deployed successfully
• ✅ Variables set at correct scope
• ✅ PR environments enabled (if needed)
• ✅ All services healthy

Initialize New Full-Stack Project

Use the automation script:

```bash

.claude/skills/railway-project-management/scripts/init-project.sh

```

Or manually:

```bash

# 1. Initialize project

railway init --name my-app

# 2. Create environments

railway environment --name staging

railway environment --name production

# 3. Add services (in production)

railway environment production

railway add --repo owner/frontend-repo

railway add --repo owner/api-repo

railway add --template postgres

# 4. Set shared variables

railway variables set --shared NODE_ENV=production

railway variables set --shared LOG_LEVEL=info

# 5. Replicate to staging

railway environment staging

# (Set staging-specific variables)

# 6. Enable PR environments (via dashboard)

railway open --settings

```

Sync Variables Between Environments

Use the automation script:

```bash

.claude/skills/railway-project-management/scripts/sync-env.sh production staging

```

Add Database to Existing Project

```bash

# 1. Switch to desired environment

railway environment production

# 2. Add database template

railway add --template postgres

# 3. Set shared DATABASE_URL

# (Usually auto-set by Railway)

# 4. Reference in other services

railway variables set DATABASE_URL='${{ postgres.DATABASE_URL }}'

```

Configure PR Environments

```bash

# 1. Enable in project settings

railway open --settings

# 2. Configure PR environment settings:

# - Base environment to duplicate

# - Services to include

# - Variable handling

# 3. PR environments auto-create on new PRs

# - Each PR gets isolated environment

# - Auto-deploys on PR updates

# - Auto-deletes on PR close/merge

```

```bash

# Service A exposes PUBLIC_URL

railway variables set --service api-service PUBLIC_URL=https://api.railway.app

# Service B references it

railway variables set --service frontend API_URL='${{ api-service.PUBLIC_URL }}'

# Service C uses multiple references

railway variables set --service worker \

API_URL='${{ api-service.PUBLIC_URL }}' \

DB_URL='${{ postgres.DATABASE_URL }}'

```

Benefits:

• DRY (Don't Repeat Yourself)
• Auto-updates when source changes
• Type-safe service connections
• Clear dependency graph

Sealed Variables

```bash

# Use sealed for production secrets

railway environment production

railway variables set --sealed STRIPE_SECRET_KEY=sk_live_...

railway variables set --sealed AWS_SECRET_ACCESS_KEY=...

# Regular variables for non-sensitive config

railway variables set --shared NODE_ENV=production

```

When to use sealed variables:

• API keys and secrets
• Database passwords
• OAuth client secrets
• Encryption keys
• Any sensitive credential

Sealed variable characteristics:

• Cannot be viewed after creation (not even in UI)
• Cannot be unsealed
• Can only be overwritten or deleted
• Enhanced security for compliance

Variable Organization

```bash

# Shared variables: Cross-service configuration

railway variables set --shared NODE_ENV=production

railway variables set --shared LOG_LEVEL=info

railway variables set --shared REGION=us-west-2

# Service variables: Service-specific config

railway variables set --service api PORT=3000

railway variables set --service api API_VERSION=v1

# Sealed variables: Secrets

railway variables set --sealed DATABASE_PASSWORD=...

railway variables set --sealed JWT_SECRET=...

```

Strategy 1: Production + Staging

```

production (main branch)

├── All services

├── Production data

└── Sealed secrets

staging (develop branch)

├── All services

├── Test data

└── Staging secrets

```

Strategy 2: Production + PR Environments

```

production (main branch)

├── All services

└── Production data

PR-123 (auto-created)

├── All services (from production template)

├── Isolated test data

└── Auto-deploys on PR updates

```

Strategy 3: Multi-Environment Pipeline

```

development → staging → production

↓ ↓ ↓

Dev data Test data Prod data

Dev URLs Stage URLs Prod URLs

```

Project Not Linked

```bash

# Symptom: "No project linked"

# Solution:

railway link

# Or specify project ID:

railway link -p abc123

```

Wrong Environment

```bash

# Check current environment

railway status

# Switch to correct environment

railway environment production

```

Variable Not Found

```bash

# List all variables to verify

railway variables list

# Check variable scope (service vs shared)

railway variables list --service api

railway variables list --shared

# Set if missing

railway variables set VAR_NAME=value

```

Service Not Deploying

```bash

# Check deployment logs

railway logs --deployment

# Check service status

railway status

# Redeploy

railway up

```

• railway-auth: Authenticate with Railway CLI
• railway-deployment: Deploy services and manage deployments
• railway-troubleshooting: Debug Railway issues
• railway-cli: Core Railway CLI operations
• railway-observability: Monitor Railway services

Project Operations

| Command | Description |

|---------|-------------|

| railway init | Initialize new project |

| railway link | Link to existing project |

| railway unlink | Unlink current project |

| railway status | Show project status |

| railway open | Open project in browser |

Environment Operations

| Command | Description |

|---------|-------------|

| railway environment | List/switch environments |

| railway environment --name | Create new environment |

| railway environment --duplicate | Duplicate current environment |

| railway environment delete | Delete environment |

Service Operations

| Command | Description |

|---------|-------------|

| railway add | Add service from current directory |

| railway add --repo | Add from GitHub |

| railway add --image | Add Docker image |

| railway add --template | Add template service |

| railway list | List all services |

Variable Operations

| Command | Description |

|---------|-------------|

| railway variables set KEY=value | Set service variable |

| railway variables set --shared KEY=value | Set shared variable |

| railway variables set --sealed KEY=value | Set sealed variable |

| railway variables delete KEY | Delete variable |

| railway variables list | List all variables |

• References:

- references/environment-types.md: Detailed environment guide

- references/variable-scoping.md: Variable scoping patterns

- references/service-sources.md: Service deployment sources

• Scripts:

- scripts/init-project.sh: Initialize complete project

- scripts/sync-env.sh: Sync variables between environments

• Railway Documentation:

- [Projects](https://docs.railway.app/reference/projects)

- [Environments](https://docs.railway.app/reference/environments)

- [Variables](https://docs.railway.app/reference/variables)

- [PR Environments](https://docs.railway.app/reference/environments#pr-environments)