turbovault-app/docs/CI_PIPELINE.md

CI/CD Pipeline Documentation

TurboVault uses GitHub Actions for continuous integration and quality assurance.

Pipeline Overview

The CI pipeline runs on:

• ✅ Every push to main or develop branches
• ✅ Every pull request to main or develop

Jobs

1. Linting & Security 🔍

Purpose: Code style and security checks

Steps:

1. RuboCop - Ruby style guide enforcement

   • Uses rubocop-rails-omakase (Rails official style guide)
   • Runs with --parallel for speed
   • Fails build if style violations found

2. Brakeman - Security vulnerability scanner

   • Scans for Rails security issues
   • continue-on-error: true (warnings don't block PRs)

Run locally:

task lint          # Check style
task lint:fix      # Auto-fix issues
task security      # Run Brakeman

2. Type Checking 🔷

Purpose: Static type checking with Sorbet

Steps:

1. Generate RBI files for gems and Rails DSLs
2. Run Sorbet type checker
3. Fails build if type errors found

Run locally:

task tapioca:all   # Generate RBI files
task typecheck     # Run type checker

Note: RBI generation can take 1-2 minutes in CI.

3. Tests 🧪

Purpose: Run test suite

Services:

• PostgreSQL 15 database

Steps:

1. Set up PostgreSQL service
2. Install system dependencies
3. Create test database
4. Load schema
5. Run test suite

Run locally:

task test          # Run all tests

4. Docker Build 🐳

Purpose: Verify Docker image builds successfully

Steps:

1. Set up Docker Buildx
2. Build production Docker image
3. Test that image runs

Run locally:

docker build -t turbovault:test .
docker run --rm turbovault:test bundle exec ruby --version

CI Workflow File

Location: .github/workflows/ci.yml

Status Badges

Status badges in README.md:

![CI](https://github.com/YOUR_USERNAME/turbovault/workflows/CI/badge.svg)
[![RuboCop](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
[![Sorbet](https://img.shields.io/badge/types-sorbet-blue.svg)](https://sorbet.org)

Don't forget to replace YOUR_USERNAME with your actual GitHub username!

What Fails the Build?

Check	Fails Build?	Why
RuboCop style issues	✅ Yes	Code style should be consistent
Brakeman security warnings	❌ No	Some warnings are false positives
Sorbet type errors	✅ Yes	Type safety is important
Test failures	✅ Yes	Tests must pass
Docker build failure	✅ Yes	Must be deployable

Fixing CI Failures

RuboCop Failures

# Auto-fix most issues
task lint:fix

# Check what's left
task lint

# Commit fixes
git add .
git commit -m "Fix RuboCop style issues"

Sorbet Type Errors

# Regenerate RBI files (if gems changed)
task tapioca:all

# Check for errors
task typecheck

# Fix type errors in code
# See docs/SORBET.md for patterns

Test Failures

# Run tests locally
task test

# Run specific test
rails test test/models/game_test.rb

# Fix tests and re-run

Docker Build Failures

# Build locally to debug
docker build -t turbovault:test .

# Check build logs for errors
# Usually missing dependencies or incorrect Dockerfile

CI Performance

Typical run times:

• Linting & Security: ~30-60 seconds
• Type Checking: ~2-3 minutes (RBI generation)
• Tests: ~1-2 minutes
• Docker Build: ~3-5 minutes

Total: ~7-11 minutes per run

Optimizations

Caching

We use bundler-cache: true in Ruby setup to cache gems:

- uses: ruby/setup-ruby@v1
  with:
    bundler-cache: true

This speeds up runs by ~1-2 minutes.

Parallel Execution

Jobs run in parallel, not sequentially:

• Linting, Type Checking, Tests, and Docker Build all run simultaneously
• Total time = slowest job (usually Docker Build)

RuboCop Parallel

RuboCop uses --parallel to check files concurrently:

bundle exec rubocop --parallel

Local Development Workflow

Before pushing:

# 1. Fix style
task lint:fix

# 2. Check types
task typecheck

# 3. Run tests
task test

# 4. Commit
git add .
git commit -m "Your changes"
git push

This ensures CI will pass!

Skipping CI

To skip CI on a commit (e.g., documentation only):

git commit -m "Update README [skip ci]"

CI for Pull Requests

When someone submits a PR:

1. CI runs automatically
2. All jobs must pass before merge
3. Status shown in PR page
4. Merge button disabled until CI passes

Viewing CI Results

On GitHub:

1. Go to repository
2. Click Actions tab
3. Click on a workflow run
4. View each job's logs

In Pull Requests:

• See status checks at bottom of PR
• Click "Details" to view logs

Troubleshooting

"RBI generation failed"

Cause: Tapioca couldn't generate RBI files

Fix: Usually transient - retry workflow. If persistent, check Gemfile.lock is committed.

"Database connection failed"

Cause: PostgreSQL service not ready

Fix: Already handled with health checks:

options: >-
  --health-cmd pg_isready
  --health-interval 10s

"Bundler version mismatch"

Cause: Different Bundler versions locally vs CI

Fix: Run bundle update --bundler locally

Advanced: Matrix Builds (Future)

To test multiple Ruby versions:

strategy:
  matrix:
    ruby-version: ['3.2', '3.3', '3.4']

Currently we only test Ruby 3.3.

Security

Secrets

We use GitHub Secrets for sensitive data:

• RAILS_MASTER_KEY (optional, for encrypted credentials)
• No other secrets needed for tests

Dependabot

Consider enabling Dependabot to auto-update dependencies:

• Settings → Security → Dependabot

Resources

• GitHub Actions Docs
• RuboCop
• Sorbet
• Brakeman

---

Questions? Check the workflow file: .github/workflows/ci.yml