adaptationio/railway-automation

Railway CI/CD Automation

Automate Railway deployments with CI/CD pipelines, migration scripts, and event-driven workflows.

Quick Start

GitHub Actions (5 minutes)

# .github/workflows/railway.yml
- uses: railway/deploy@v1
  with:
    railway_token: ${{ secrets.RAILWAY_TOKEN }}
    service: api

GitLab CI (5 minutes)

# .gitlab-ci.yml
deploy:
  script:
    - railway up --service api
  only: [main]

Migration (10 minutes)

./scripts/migrate.sh --from heroku --project myapp

Workflow Overview

1. GitHub Actions Integration

Setup Process

1. Generate Railway token (railway login && railway token)
2. Add token to GitHub secrets (RAILWAY_TOKEN)
3. Create workflow file (.github/workflows/railway.yml)
4. Configure deployment triggers
5. Test with PR or push

Use Cases

• Deploy on push to main/staging
• PR preview environments
• Multi-environment promotion
• Scheduled deployments
• Manual approval gates

Template: See templates/github-workflow.yml

Reference: references/github-actions.md for complete guide with 5+ workflow examples

---

2. GitLab CI Integration

Setup Process

1. Generate Railway token
2. Add to GitLab CI/CD variables (RAILWAY_TOKEN)
3. Create .gitlab-ci.yml
4. Define stages (test → staging → production)
5. Configure manual gates

Use Cases

• Multi-stage pipelines
• Environment-specific deployments
• Review apps for merge requests
• Parallel service deployments
• Artifact-based deployments

Template: See templates/gitlab-ci.yml

Reference: references/gitlab-ci.md for complete guide with pipeline examples

---

3. Custom CI/CD Integration

Generic Pattern (Any Platform)

# Install Railway CLI
npm i -g @railway/cli

# Login with token
export RAILWAY_TOKEN=$YOUR_TOKEN

# Link project
railway link $PROJECT_ID

# Deploy
railway up --service $SERVICE_NAME --environment $ENVIRONMENT

Environment Variables

• RAILWAY_TOKEN: Authentication token
• RAILWAY_PROJECT_ID: Project identifier (optional if linked)
• RAILWAY_SERVICE: Service name (optional)
• RAILWAY_ENVIRONMENT: Environment name (optional)

Health Check Pattern

# Deploy and wait for health
railway up --service api
sleep 30

# Verify deployment
DEPLOY_URL=$(railway status --json | jq -r '.url')
curl -f $DEPLOY_URL/health || exit 1

Supported Platforms

• CircleCI
• Travis CI
• Jenkins
• Bitbucket Pipelines
• Azure DevOps
• Any platform with shell access

---

4. Migration Automation

Interactive Migration Script

# From Heroku
./scripts/migrate.sh --from heroku --project myapp

# From Vercel
./scripts/migrate.sh --from vercel --project myapp --env production

# Dry run (preview changes)
./scripts/migrate.sh --from render --project myapp --dry-run

Script Features

• Platform detection
• Environment variable export/import
• Railway project creation
• Service configuration
• Database migration
• DNS cutover planning
• Verification checks

Supported Migrations

• Heroku → Railway
• Vercel → Railway
• Render → Railway
• Docker Compose → Railway
• Kubernetes → Railway

Reference: references/migration-patterns.md for detailed guides per platform

---

5. Scheduled Tasks

Cron-Based Deployments

# GitHub Actions - Deploy every night at 2 AM
on:
  schedule:
    - cron: '0 2 * * *'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: railway/deploy@v1
        with:
          railway_token: ${{ secrets.RAILWAY_TOKEN }}

Database Backups

# Scheduled backup workflow
on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

jobs:
  backup:
    steps:
      - name: Backup database
        run: |
          railway run pg_dump > backup.sql
          aws s3 cp backup.sql s3://backups/$(date +%Y%m%d).sql

Health Check Monitoring

# Hourly health checks
on:
  schedule:
    - cron: '0 * * * *'

jobs:
  health:
    steps:
      - name: Check service health
        run: |
          curl -f ${{ secrets.SERVICE_URL }}/health || \
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -d '{"text":"Service down!"}'

---

6. Webhook Integration

GitHub Webhook → Railway Deploy

// Webhook handler
app.post('/webhook/github', async (req, res) => {
  const { ref, repository } = req.body;

  if (ref === 'refs/heads/main') {
    const { exec } = require('child_process');
    exec('railway up --service api', (error, stdout) => {
      console.log(stdout);
    });
  }

  res.json({ status: 'ok' });
});

Railway Webhook Events Railway supports webhooks for:

• Deployment started
• Deployment completed
• Deployment failed
• Service crashed
• Build logs

Configure Webhooks

# Via Railway CLI
railway webhooks add \
  --url https://yourapp.com/webhook \
  --events deployment.success,deployment.failure

# Via API
curl -X POST https://backboard.railway.app/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "mutation { webhookCreate(input: {...}) }"
  }'

Notification Integration

# Slack notification on deploy
railway webhooks add \
  --url $SLACK_WEBHOOK_URL \
  --events deployment.success \
  --transform '{
    "text": "Deployed {{service}} to {{environment}}"
  }'

---

Common Patterns

Multi-Environment Deployment

# Deploy to staging first, then production
jobs:
  staging:
    environment: staging
    steps:
      - uses: railway/deploy@v1
        with:
          railway_token: ${{ secrets.RAILWAY_TOKEN }}
          environment: staging

  production:
    needs: staging
    environment: production
    steps:
      - uses: railway/deploy@v1
        with:
          railway_token: ${{ secrets.RAILWAY_TOKEN }}
          environment: production

PR Preview Environments

# Create preview for each PR
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    steps:
      - uses: railway/deploy@v1
        with:
          railway_token: ${{ secrets.RAILWAY_TOKEN }}
          service: api-pr-${{ github.event.pull_request.number }}

Rollback on Failure

# Automatic rollback if health check fails
jobs:
  deploy:
    steps:
      - name: Deploy
        id: deploy
        run: railway up --service api

      - name: Health check
        run: curl -f $SERVICE_URL/health

      - name: Rollback on failure
        if: failure()
        run: railway rollback --service api

Matrix Deployments

# Deploy multiple services in parallel
strategy:
  matrix:
    service: [api, worker, cron]

steps:
  - uses: railway/deploy@v1
    with:
      railway_token: ${{ secrets.RAILWAY_TOKEN }}
      service: ${{ matrix.service }}

---

Token Management

Generate Token

# CLI method
railway login
railway token

# Copy token to clipboard
railway token | pbcopy  # macOS
railway token | xclip   # Linux

Add to CI Platform

GitHub

Settings → Secrets and variables → Actions → New repository secret
Name: RAILWAY_TOKEN
Value: [paste token]

GitLab

Settings → CI/CD → Variables → Add variable
Key: RAILWAY_TOKEN
Value: [paste token]
Protected: Yes
Masked: Yes

CircleCI

Project Settings → Environment Variables → Add Variable
Name: RAILWAY_TOKEN
Value: [paste token]

Token Rotation

# Generate new token
NEW_TOKEN=$(railway token)

# Update in CI (platform-specific)
# Then invalidate old token via dashboard

---

Environment-Specific Configuration

Detect Environment in Code

const env = process.env.RAILWAY_ENVIRONMENT || 'development';

const config = {
  development: { db: 'localhost:5432' },
  staging: { db: process.env.DATABASE_URL },
  production: { db: process.env.DATABASE_URL }
};

export default config[env];

Conditional Deployment

# Only deploy staging on feature branches
jobs:
  deploy-staging:
    if: github.ref != 'refs/heads/main'
    steps:
      - uses: railway/deploy@v1
        with:
          environment: staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: railway/deploy@v1
        with:
          environment: production

Environment Variable Management

# Export from staging
railway env --environment staging > .env.staging

# Import to production (selective)
cat .env.staging | grep -v SECRET | railway env --environment production

---

Best Practices

Security

• Use masked/protected CI variables
• Rotate tokens quarterly
• Use service tokens (not personal) for production
• Never commit tokens to git
• Limit token scope to specific projects

Performance

• Cache dependencies in CI
• Use Railway's built-in caching
• Deploy only changed services
• Run tests before deploy
• Use health checks before traffic

Reliability

• Always include rollback mechanism
• Monitor deployment notifications
• Set deployment timeouts
• Use staging before production
• Test migrations in preview environments

Monitoring

• Log all deployments
• Track deployment duration
• Alert on failures
• Monitor health checks
• Track rollback frequency

---

Troubleshooting

Deployment Fails in CI

# Check token validity
railway whoami

# Verify project link
railway status

# Check service exists
railway list

# View deployment logs
railway logs --service api

Token Authentication Errors

# Regenerate token
railway logout
railway login
railway token

# Update in CI secrets
# Test locally first
RAILWAY_TOKEN=$NEW_TOKEN railway status

Environment Not Found

# List available environments
railway environment list

# Verify environment name matches
railway status --environment production

Service Not Deploying

# Check service name
railway list

# Verify service configuration
railway status --service api

# Check for build errors
railway logs --service api --deployment latest

---

Related Skills

• railway-auth: Token management and authentication setup
• railway-api: Programmatic Railway API automation
• railway-deployment: Deployment patterns and strategies
• railway-database: Database automation and backups
• railway-monitoring: Health checks and alerting

---

References

• references/github-actions.md: Complete GitHub Actions guide with 5+ workflow examples
• references/gitlab-ci.md: Complete GitLab CI guide with pipeline examples
• references/migration-patterns.md: Platform migration guides (Heroku, Vercel, Render, etc.)

Templates

• templates/github-workflow.yml: Production-ready GitHub Actions template
• templates/gitlab-ci.yml: Production-ready GitLab CI template

Scripts

• scripts/migrate.sh: Interactive migration script supporting multiple platforms