Rails Setup Flow

---
name: rails-setup-flow
license: MIT
description: >
  Complete Rails project setup workflow. Installs dependencies via Bundler, configures database
  connections, generates Rails app scaffold, validates the dev environment, and generates GitHub
  Actions or GitLab CI pipelines with linting, testing, and security scanning. Use when starting
  a new Rails project, running `rails new`, configuring a Gemfile or .ruby-version, setting up a
  development environment, or wiring up CI/CD for a Ruby on Rails app. Trigger: setup project,
  new Rails app, configure CI/CD, dev environment setup, rails new, Gemfile setup, .ruby-version,
  Ruby on Rails project bootstrap.
keywords: rails, setup, onboarding, ci/cd, workflow, devops, configuration
---

# Rails Setup Flow — Complete Project Setup Workflow

Orchestrates the full Rails project setup from context gathering through CI/CD configuration.

## When to Use

- Starting a new Rails project (`rails new` or existing repo clone)
- Setting up development environment for existing project
- Configuring CI/CD pipeline
- Docker/environment setup

## Workflow Phases

### Phase 1: Context & Onboarding

**Load project context first:**
1. **skills/context/rails-context-engineering** — Understand existing codebase structure
2. **skills/context/rails-project-onboarding** — Complete dev environment setup

**Inline fallback (if sub-skills are unavailable):**
```bash
# Verify Ruby version matches .ruby-version
ruby -v
# Install dependencies
bundle install
# Check database connectivity
rails db:create db:migrate
# Confirm test runner is operational
bundle exec rspec --dry-run
# Load env vars (copy example if missing)
cp .env.example .env 2>/dev/null || true
```

**HARD GATE — Environment Check:**
- Ruby version correct (check `.ruby-version`)
- Bundler installed and working
- Database connection successful
- All env vars loaded (check `config/credentials.yml.enc` or `.env`)

**If environment check FAILS:** Fix the failing item above before proceeding to Phase 2.

---

### Phase 2: CI/CD Configuration

**Proceed only after environment check passes.**

1. **CI/CD Proposal Checkpoint** — Decide on pipeline approach:
   - GitHub Actions, GitLab CI, or other platform?
   - Staging vs production environments?
   - Deployment strategy (basic, blue-green, canary)?

2. **Configure CI pipeline** (linting, testing, security, migrations):

```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true
      - run: bundle exec rails db:create db:migrate
      - run: bundle exec rspec
      - run: bundle exec rubocop
      - run: bundle exec brakeman --no-pager
      - run: bundle exec bundle-audit check --update
```

3. **Configure CD pipeline** (staging + production deployment gates):

```yaml
# .github/workflows/cd.yml
name: CD
on:
  push:
    branches: [main]
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true
      - run: bundle exec rails db:migrate
        env:
          RAILS_ENV: staging
          DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL }}
      - run: echo "Deploy to staging here (e.g. Heroku, Fly.io, Kamal)"
  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment: production   # Requires manual approval gate in GitHub
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true
      - run: bundle exec rails db:migrate
        env:
          RAILS_ENV: production
          DATABASE_URL: ${{ secrets.PRODUCTION_DATABASE_URL }}
      - run: echo "Deploy to production here"
      # Rollback: re-run previous deployment job or use platform CLI
```

---

### Phase 3: Environment Validation

**Verify everything works end-to-end:**

```bash
# Local development
bundle install
rails db:create db:migrate
rails server  # Should start without errors
bundle exec rspec  # Should run (even if 0 tests)

# CI simulation (if possible locally)
act push  # GitHub Actions local runner (optional)
```

---

## Output Style

**Setup Checklist:** Marked file `SETUP_CHECKLIST.md` with:
- [ ] Ruby installed
- [ ] Bundler working
- [ ] Database created
- [ ] Tests passing
- [ ] CI configured
- [ ] Secrets configured

## Integration

| Predecessor | This Skill | Successor |
|-------------|------------|-----------|
| None (entry point) | rails-setup-flow | rails-tdd-loop (start developing) |
| None (entry point) | rails-setup-flow | create-prd (plan features first) |

**From AGENTS.md:** This is the setup workflow. For development, chain to rails-tdd-loop.