railway-deployment

This skill provides comprehensive deployment management for Railway:

• Deploy from sources: GitHub auto-deploy, Docker images, local directory
• Monitor deployments: Real-time logs, status tracking, build progress
• Verify health: Automated health checks and validation
• Rollback strategies: Safe rollback to previous deployments
• Environment management: Staging → production workflows
• CI/CD integration: Automated deployment pipelines

• Railway CLI installed and authenticated (use railway-auth skill)
• Project linked (use railway-project-management skill)
• Service created in target environment

• Deploying new code to Railway
• Redeploying after configuration changes
• Rolling back failed deployments
• Promoting staging to production
• Setting up automated deployments
• Monitoring deployment progress
• Verifying deployment health

---

Step 1: Prepare Deployment

Verify authentication, project context, and service health before deploying.

Commands:

```bash

# Verify authentication

railway whoami

# Check project and environment context

railway status

# List services in current environment

railway list

# Check current deployment status

railway status --json

```

Pre-deployment checklist:

• [ ] Authenticated with Railway
• [ ] Correct project linked
• [ ] Target environment selected
• [ ] Service exists in environment
• [ ] No pending deployments
• [ ] Environment variables set

Use automation:

```bash

.claude/skills/railway-deployment/scripts/pre-deploy-check.sh

```

---

Step 2: Deploy

Deploy from GitHub, Docker, or local directory.

#### Deploy from GitHub (Auto-Deploy)

Setup auto-deploy:

```bash

# Link service to GitHub repo

railway add --repo owner/repository

# Configure branch (via dashboard or railway.json)

railway open

```

Trigger deployment:

```bash

# Push to configured branch

git push origin main

# Railway automatically deploys

# Monitor in real-time:

railway logs --deployment

```

Manual redeploy:

```bash

# Redeploy latest commit

railway redeploy

# Redeploy specific deployment ID

railway redeploy --deployment

```

#### Deploy from Local Directory

Deploy current directory:

```bash

# Deploy and wait for completion

railway up

# Deploy without waiting (detached)

railway up --detach

# Deploy in CI mode (build logs only)

railway up --ci

# Deploy specific service

railway up --service backend

```

What happens:

1. CLI uploads local directory to Railway
2. Railway detects build configuration (Nixpacks/Dockerfile)
3. Build starts automatically
4. Deployment triggers on successful build
5. Service restarts with new code

#### Deploy from Docker Image

Public image:

```bash

# Deploy Docker Hub image

railway add --image postgres:15

# Deploy with tag

railway add --image myapp/backend:v1.2.3

```

Private registry:

```bash

# Set registry credentials

railway variables set --sealed DOCKER_USERNAME=user

railway variables set --sealed DOCKER_PASSWORD=pass

# Deploy from private registry

railway add --image registry.example.com/app:latest

```

Update image tag (rollback/upgrade):

```bash

# Via environment variable

railway variables set IMAGE_TAG=v1.2.2

# Force redeploy with new tag

railway redeploy

```

See references/deployment-sources.md for detailed configuration.

---

Step 3: Monitor Deployment

Track deployment progress and identify issues in real-time.

Real-time logs:

```bash

# Follow deployment logs

railway logs --deployment

# Filter by service

railway logs --service backend --deployment

# Show last 100 lines

railway logs --tail 100

# Include timestamps

railway logs --timestamps

```

Deployment status:

```bash

# Check deployment status

railway status

# Get detailed JSON status

railway status --json | jq '.deployments[0]'

# List recent deployments

railway list deployments

# Check specific deployment

railway deployment

```

Build progress indicators:

```

Building... ████████░░░░░░░░ 60%

Installing dependencies...

Running build script...

Optimizing assets...

```

Watch for issues:

• Build failures (missing dependencies)
• Environment variable errors
• Port binding issues
• Memory/CPU limits exceeded
• Health check failures

Automated monitoring:

```bash

# Monitor and alert on failures

.claude/skills/railway-deployment/scripts/monitor-deployment.sh

```

---

Step 4: Verify Deployment

Validate that deployment is healthy and functioning correctly.

Health check commands:

```bash

# Check service health endpoint

curl https://your-service.railway.app/health

# Verify with custom validation

.claude/skills/railway-deployment/scripts/verify-health.sh

```

Validation checklist:

• [ ] Service is running (not crashed)
• [ ] Health endpoint returns 200 OK
• [ ] Environment variables loaded correctly
• [ ] Database connections established
• [ ] API endpoints responding
• [ ] Static assets loading
• [ ] No error logs present

Automated validation:

```bash

# Run full health check suite

.claude/skills/railway-deployment/scripts/deploy.sh --verify

# Output:

# ✅ Service running

# ✅ Health check passed (200 OK)

# ✅ Environment variables loaded

# ✅ Database connection successful

# ✅ API responding correctly

```

Common validation issues:

| Issue | Symptom | Solution |

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

| Service not starting | Status: "crashed" | Check logs for startup errors |

| Health check failing | 503 Service Unavailable | Verify health endpoint path |

| Variables missing | Application errors | Check railway variables list |

| Port binding error | "EADDRINUSE" | Ensure PORT variable used |

| Database connection | "ECONNREFUSED" | Verify DATABASE_URL set |

---

Step 5: Rollback if Needed

Safely rollback to previous deployment if issues are detected.

Quick rollback:

```bash

# Redeploy previous deployment

railway redeploy --deployment

# List recent deployments to find ID

railway list deployments

```

Automated rollback:

```bash

# Rollback with safety checks

.claude/skills/railway-deployment/scripts/rollback.sh

# Rollback to specific version

.claude/skills/railway-deployment/scripts/rollback.sh v1.2.3

```

Rollback strategies:

1. Redeploy Previous Commit (GitHub):

```bash

# Find previous working commit

git log --oneline

# Revert to previous commit

git revert HEAD

git push origin main

# Railway auto-deploys

```

1. Redeploy Previous Deployment (any source):

```bash

# List deployments

railway list deployments

# Redeploy specific deployment ID

railway redeploy --deployment dep_abc123xyz

```

1. Docker Image Tag Rollback:

```bash

# Update image tag to previous version

railway variables set IMAGE_TAG=v1.2.2

# Redeploy with previous tag

railway redeploy

```

1. Environment Variable Rollback:

```bash

# Restore previous variable values

railway variables set API_VERSION=v1

railway variables set FEATURE_FLAGS=old-config

# Redeploy with previous config

railway redeploy

```

See references/rollback-strategies.md for detailed rollback procedures.

Rollback verification:

```bash

# After rollback, verify health

.claude/skills/railway-deployment/scripts/verify-health.sh

# Check logs for errors

railway logs --tail 50

# Verify specific functionality

curl https://your-service.railway.app/api/test

```

---

Typical promotion flow:

```bash

# 1. Deploy to staging first

railway environment staging

railway up

# 2. Verify staging deployment

.claude/skills/railway-deployment/scripts/verify-health.sh

# 3. Run staging tests

npm run test:staging

# 4. Promote to production

railway environment production

# 5. Deploy same code

railway up

# 6. Verify production

.claude/skills/railway-deployment/scripts/verify-health.sh

# 7. Monitor production logs

railway logs --deployment

```

Automated staging workflow:

```bash

# Complete staging → production workflow

.claude/skills/railway-deployment/scripts/promote-to-production.sh

```

See references/staging-workflow.md for detailed staging strategies.

---

GitHub Actions

```yaml

name: Deploy to Railway

on:

push:

branches: [main]

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Install Railway CLI

run: npm install -g @railway/cli

- name: Deploy to Railway

env:

RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

run: |

railway up --ci

- name: Verify Deployment

run: |

sleep 30

curl -f https://your-service.railway.app/health || exit 1

```

GitLab CI

```yaml

deploy:staging:

stage: deploy

image: node:20

script:

- npm install -g @railway/cli

- railway environment staging

- railway up --ci

environment:

name: staging

only:

- develop

deploy:production:

stage: deploy

image: node:20

script:

- npm install -g @railway/cli

- railway environment production

- railway up --ci

environment:

name: production

only:

- main

when: manual

```

---

Blue-Green Deployment

```bash

# 1. Deploy to "green" environment

railway environment green

railway up

# 2. Verify green is healthy

.claude/skills/railway-deployment/scripts/verify-health.sh

# 3. Switch traffic to green

# (Update DNS or load balancer)

# 4. Keep blue as rollback option

railway environment blue

# (Don't delete until green is stable)

```

Canary Deployment

```bash

# 1. Deploy canary version

railway environment canary

railway up

# 2. Route small % of traffic to canary

# (Configure via load balancer)

# 3. Monitor canary metrics

railway logs --service canary

# 4. Gradually increase traffic

# (Adjust load balancer weights)

# 5. Promote to production if successful

railway environment production

railway up

```

Rolling Deployment

```bash

# Deploy to instances one at a time

# (Requires horizontal scaling)

# Railway handles rolling deploys automatically

# when multiple replicas are configured

railway up

# Monitors health and rolls back on failure

```

---

Build Failures

```bash

# Check build logs

railway logs --deployment

# Common issues:

# - Missing package.json

# - Node/Python version mismatch

# - Build command failures

# - Environment variables not set

# Fix and redeploy

railway up

```

Deployment Stuck

```bash

# Check deployment status

railway status --json

# Cancel stuck deployment

railway deployment cancel

# Redeploy

railway up

```

Health Check Failures

```bash

# Check service logs

railway logs

# Verify health endpoint exists

curl -v https://your-service.railway.app/health

# Check port configuration

railway variables list | grep PORT

# Verify restart policy

railway open # Check service settings

```

Memory/CPU Limits

```bash

# Check resource usage

railway metrics

# Increase limits (via dashboard)

railway open

# Or upgrade plan

```

---

Core Deployment Commands

| Command | Description |

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

| railway up | Deploy local directory |

| railway up --detach | Deploy without waiting |

| railway up --ci | Deploy in CI mode |

| railway redeploy | Redeploy latest deployment |

| railway logs --deployment | Monitor deployment logs |

| railway status | Check deployment status |

Deployment Sources

| Source | Command | Auto-Deploy |

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

| GitHub | railway add --repo owner/repo | ✅ Yes (on push) |

| Local | railway up | ❌ Manual |

| Docker | railway add --image image:tag | ❌ Manual |

Environment Workflow

```bash

# Staging

railway environment staging

railway up

# Production

railway environment production

railway up

```

---

Smart Deployment with Health Checks

```bash

# Deploy with automatic health verification

.claude/skills/railway-deployment/scripts/deploy.sh

# Deploy specific service

.claude/skills/railway-deployment/scripts/deploy.sh backend

# Deploy with custom health endpoint

.claude/skills/railway-deployment/scripts/deploy.sh backend /api/health

```

Safe Rollback

```bash

# Rollback with confirmation prompt

.claude/skills/railway-deployment/scripts/rollback.sh

# Rollback to specific deployment

.claude/skills/railway-deployment/scripts/rollback.sh dep_abc123

# Emergency rollback (no confirmation)

.claude/skills/railway-deployment/scripts/rollback.sh --force

```

Pre-Deployment Validation

```bash

# Check all prerequisites

.claude/skills/railway-deployment/scripts/pre-deploy-check.sh

# Validates:

# - Railway authentication

# - Project linked

# - Environment selected

# - No pending deployments

# - Variables configured

```

---

• railway-auth: Authenticate with Railway CLI and manage tokens
• railway-project-management: Create projects, manage environments, configure variables
• railway-observability: Monitor metrics, logs, and traces
• railway-api: GraphQL API automation for advanced workflows

---

• References:

- references/deployment-sources.md: GitHub, Docker, and local deployment details

- references/rollback-strategies.md: Comprehensive rollback procedures

- references/staging-workflow.md: Staging → production best practices

• Scripts:

- scripts/deploy.sh: Smart deployment with health checks

- scripts/rollback.sh: Safe rollback with confirmation

- scripts/verify-health.sh: Automated health validation

- scripts/pre-deploy-check.sh: Pre-deployment validation

- scripts/promote-to-production.sh: Staging → production automation

• Railway Documentation:

- [Deployments](https://docs.railway.app/reference/deployments)

- [CLI Commands](https://docs.railway.app/reference/cli-api)

- [GitHub Integration](https://docs.railway.app/guides/github-integration)

- [Docker Deployments](https://docs.railway.app/guides/dockerfiles)

---

Last Updated: November 2025

Status: Production-ready

Version: 1.0.0