Railway Project Management

Comprehensive management of Railway.com projects, environments, services, and variables using the Railway CLI.

Overview

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

Prerequisites

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

Workflow

1. Project Creation and Linking

Create new Railway project:

# 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 <project-id>

# Link to project with specific environment and service
railway link -p <project-id> -e <environment-id> -s <service-id>

# Check current project status
railway status

Project information:

# View project details
railway status

# View project in browser
railway open

# Unlink from current project
railway unlink

2. Environment Management

Create and switch environments:

# 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:

# 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:

# 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:

# 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:

# View service in browser
railway open

# Configure via railway.json or railway.toml
cat > railway.json <<EOF
{
  "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:

# 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 ver

...