GitHub CI/CD Pipeline Setup for Rails Backend

OverviewCopy Anchor Link

This project now has a focused staging deployment pipeline using GitHub Actions and Capistrano. The pipeline automatically runs tests and deploys to staging when pushing to the develop branch.

Files Created/UpdatedCopy Anchor Link

1. GitHub Actions WorkflowCopy Anchor Link

Staging Deployment Pipeline (.github/workflows/deploy-staging.yml)Copy Anchor Link

• Triggers: Push to develop branch, pull requests to develop
• Jobs:
  • test: Runs all RSpec tests in backend/parts/, RuboCop, security scans
  • deploy-staging: Deploys to staging when pushing to develop (only on pushes, not PRs)

Deployment Plan Documentation (STAGING-DEPLOYMENT-PLAN.md)Copy Anchor Link

• Complete step-by-step setup instructions
• GitHub repository configuration guide
• SSH key setup instructions
• Troubleshooting guide

Required GitHub SecretsCopy Anchor Link

You need to configure these secrets in your GitHub repository settings:

Required for Staging DeploymentCopy Anchor Link

• STAGING_SSH_KEY: Private SSH key for staging server (148.113.37.48)
• DEPLOY_USER: SSH username for server (e.g., deploy)
• RAILS_MASTER_KEY_STAGING: Rails master key for staging environment
• AWS_REGION: AWS region for services (e.g., ap-south-1)

GitHub Setup InstructionsCopy Anchor Link

Step 1: Configure GitHub RepositoryCopy Anchor Link

1.1 Create Staging EnvironmentCopy Anchor Link

1. Go to your repository on GitHub
2. Navigate to Settings → Environments
3. Click New environment
4. Name: staging
5. Environment URL: https://api-stg.kulcare.com
6. Set protection rules as needed

1.2 Add GitHub SecretsCopy Anchor Link

1. Go to Settings → Secrets and variables → Actions
2. Add these repository secrets:
   • STAGING_SSH_KEY: Private SSH key content
   • DEPLOY_USER: SSH username (e.g., deploy)
   • RAILS_MASTER_KEY_STAGING: Rails master key for staging

Step 2: Generate SSH KeysCopy Anchor Link

2.1 Create SSH Key PairCopy Anchor Link

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "github-actions@kulcare" -f github-actions-key

# View private key (add to GitHub secrets)
cat github-actions-key

# View public key (add to staging server)
cat github-actions-key.pub

2.2 Add Public Key to Staging ServerCopy Anchor Link

# On staging server (148.113.37.48)
ssh-copy-id -i github-actions-key.pub deploy@148.113.37.48

# Or manually add to authorized_keys
echo "PUBLIC_KEY_CONTENT" >> /home/deploy/.ssh/authorized_keys

Deployment ConfigurationCopy Anchor Link

Current SetupCopy Anchor Link

• Staging Server: 148.113.37.48 (api-stg.kulcare.com)
• Deployment User: deploy
• Branch Strategy: develop → Staging deployment
• Production: Will be implemented later for master branch

Capistrano ConfigurationCopy Anchor Link

Your existing Capistrano setup is used:

• Command: bundle exec cap staging deploy
• Puma: Application server with systemd integration
• Sidekiq: Background job processing
• Database: PostgreSQL
• Redis: Caching and job queue
• Assets: Precompiled during deployment

How the Pipeline WorksCopy Anchor Link

1. Development Push (to develop branch)Copy Anchor Link

git push origin develop
↓
[CI] Run Tests → Security Scans
  - All RSpec tests in backend/parts/
  - RuboCop code style checking
  - Brakeman security scan
  - Bundle audit for vulnerabilities
↓
[CD] Deploy to Staging Server (148.113.37.48)
↓
Health Check on api-stg.kulcare.com
↓
Deployment Summary in GitHub Actions

2. Pull Request to develop branchCopy Anchor Link

Create PR targeting develop branch
↓
[CI] Run Tests → Security Scans (only tests, no deployment)
↓
Results shown in PR checks

3. Production Deploy (Future)Copy Anchor Link

git push origin master (when implemented)
↓
[CI] Run Tests → Security Scans
↓
[CD] Deploy to Production Server

RSpec Test SuiteCopy Anchor Link

The workflow automatically runs all RSpec tests using bundle exec rspec, which picks up all test files in:

• backend/spec/ (traditional Rails tests)
• backend/parts/*/spec/ (parts-based modular tests)
• Total: 298 test files across all parts

Test Categories CoveredCopy Anchor Link

• Unit Tests: Models, services, interactors
• Integration Tests: API controllers, workflows
• Feature Tests: End-to-end business scenarios
• Parts-specific Tests: Domain logic for each part (auth, billing, clinic, etc.)

Server RequirementsCopy Anchor Link

Staging Server Setup (148.113.37.48)Copy Anchor Link

• Ubuntu server with SSH access
• User deploy with proper permissions
• Ruby 3.2.0 installed
• PostgreSQL, Redis, Nginx configured
• Capistrano deployment directory configured
• SSH public key added to authorized_keys

Environment VariablesCopy Anchor Link

Required on Staging ServerCopy Anchor Link

The workflow provides these environment variables during deployment:

• RAILS_ENV=staging
• RAILS_MASTER_KEY (from GitHub secrets)
• Other variables should be configured on the server

Monitoring and Health ChecksCopy Anchor Link

The pipeline includes comprehensive health checks:

• Tests multiple endpoints: /health, /api/v1/health, /up, /ping, root
• HTTP response validation (200 or 302 status codes)
• Deployment status summary in GitHub Actions
• Application accessibility verification

Rollback ProcedureCopy Anchor Link

If a deployment fails:

1. Capistrano automatically keeps the previous version
2. Use bundle exec cap staging rollback to revert manually
3. Check deployment logs: bundle exec cap staging logs
4. Monitor GitHub Actions logs for detailed error information

Testing LocallyCopy Anchor Link

Before pushing changes:

cd backend

# Run all tests (same as CI)
bundle exec rspec

# Check code style
bundle exec rubocop

# Check security vulnerabilities
bundle exec brakeman
bundle exec bundle audit --update

# Test Capistrano configuration
bundle exec cap staging deploy:check

TroubleshootingCopy Anchor Link

Common IssuesCopy Anchor Link

1. SSH Key Errors:

   • Verify STAGING_SSH_KEY secret is correctly configured
   • Check that public key is added to server's authorized_keys
   • Ensure deploy user permissions are correct

2. Test Failures:

   • Check test environment setup
   • Verify database schema is loaded
   • Review test logs in GitHub Actions

3. Deployment Failures:

   • Check Capistrano configuration
   • Verify server environment variables
   • Review deployment logs in GitHub Actions

Debug CommandsCopy Anchor Link

# Check deployment status
bundle exec cap staging deploy:status

# View recent deployment logs
bundle exec cap staging logs

# Connect to staging server
bundle exec cap staging ssh

# Verify SSH connection (from local)
ssh -i private-key deploy@148.113.37.48 "echo 'Connection successful'"

Security NotesCopy Anchor Link

• SSH keys should be passwordless and properly secured
• Never commit secrets to your repository
• Use GitHub secrets for all sensitive data
• Security scans (Brakeman, bundle audit) run automatically
• Regularly update Ruby gems and dependencies

Quick Start GuideCopy Anchor Link

1. Setup GitHub RepositoryCopy Anchor Link

# Create staging environment
# Add GitHub secrets: STAGING_SSH_KEY, DEPLOY_USER, RAILS_MASTER_KEY_STAGING

2. Setup SSH KeysCopy Anchor Link

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -C "github-actions@kulcare" -f github-actions-key

# Add private key to GitHub secrets
cat github-actions-key

# Add public key to staging server
ssh-copy-id -i github-actions-key.pub deploy@148.113.37.48

3. Test DeploymentCopy Anchor Link

# Push to develop branch
git checkout develop
git add .
git commit -m "Setup GitHub Actions staging deployment"
git push origin develop

# Monitor deployment in GitHub Actions tab

This setup provides automated testing, security scanning, and safe staging deployments with comprehensive monitoring and rollback capabilities.