pg_multitenant_schemas 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb953481e57f8425d7a272414d51e9225d224f6975f7e519051566f8e6c58406
-  data.tar.gz: 3512040a1448b3a8cca8f829717ecc373510234bc53e2d84243272ea16903846
+  metadata.gz: 4523327235e126955f182413b00ecab417f260daf3b0ed550ece95bc1da7a8bf
+  data.tar.gz: 4f277b6139588035c3d04befb30b475ad55fd7a199d582e7728aed15757dcc7c
 SHA512:
-  metadata.gz: c4e77e04b02112a32d8ac953ab0c88a662cc599ec1fc498f6c3205c3a4596ba74e26c514add5de50df58414ff4dfd62a65241e2dbe26f1dbfcdd3093eab25426
-  data.tar.gz: 267b65ce20ab82f817c1ecd959dcd3781ad7f0b00434a381cf3a7968cf1e5363bf57519d26e07cf3bc9d75b90797f2b394c2a3bca8ef060b52e01768ce8c10e4
+  metadata.gz: a454ee397a247ea820b89590c0e9c8d10f63e83507f4b989b27780b8721c99b5191fe9048f7cf378d9388371650524b48adcf4a4ec58c2566aa2e0afdfb66929
+  data.tar.gz: 6adc8a9a67ff69b2e045982ff85a48f045a683614bb548343bc64e78062c01b191e5e70984c8ed3dd110696bd556f51def524dd2619f1a5d20cd43f3eeafcb9a

data/.actrc

@@ -0,0 +1,17 @@
+# act configuration file
+# This configures act to run GitHub Actions locally
+
+# Use Linux AMD64 architecture for compatibility
+--container-architecture linux/amd64
+
+# Set artifact server path
+--artifact-server-path /tmp/act-artifacts
+
+# Load environment variables from local file
+--env-file .env.local
+
+# Use medium size runner image
+--platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Show more verbose output
+--verbose

data/.env.local.example

@@ -0,0 +1,21 @@
+# Local environment variables for testing with act
+# Copy this to .env.local and fill in your actual values
+
+# GitHub token (create at https://github.com/settings/tokens)
+# Needs repo and workflow permissions
+GITHUB_TOKEN=your_github_token_here
+
+# RubyGems API key (get from https://rubygems.org/profile/edit)
+# Only needed for testing release workflow
+RUBYGEMS_API_KEY=your_rubygems_api_key_here
+
+# Repository information
+GITHUB_REPOSITORY=rubenpazch/pg_multitenant_schemas
+GITHUB_ACTOR=your_github_username
+
+# PostgreSQL configuration for local testing
+PGDATABASE=pg_multitenant_test
+PGUSER=postgres
+PGPASSWORD=
+PGHOST=localhost
+PGPORT=5432

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2025-09-07
+
+### 🔧 **Developer Experience & Testing**
+- **NEW: Local Workflow Testing**: Complete solution for testing GitHub Actions locally before push
+- **NEW: Pre-Push Validation**: `pre-push-check.sh` script validates CI components locally  
+- **NEW: GitHub Actions Testing**: `act` tool integration with configuration files
+- **NEW: Validation Scripts**: `validate-github-commands.sh` and `test-github-setup.sh`
+
+### 🚀 **CI/CD Improvements**
+- **FIXED: GitHub Actions Permissions**: Resolved permission issues with release workflow
+- **FIXED: RSpec Command**: Corrected `--exclude-pattern` usage for unit test isolation
+- **IMPROVED: Release Automation**: Enhanced release workflow with proper bot identity
+- **IMPROVED: Documentation**: Comprehensive guides for CI/CD setup and troubleshooting
+
+### 📚 **Documentation Enhancements**
+- **NEW: Local Testing Guide**: `TESTING_LOCALLY.md` and `LOCAL_TESTING_SUMMARY.md`
+- **NEW: CI/CD Setup Guide**: `docs/github_actions_setup.md` with step-by-step instructions
+- **NEW: Permissions Fix Guide**: `docs/github_actions_permissions_fix.md`
+- **NEW: Workflow Testing Guide**: `docs/local_workflow_testing.md`
+- **IMPROVED: Core Documentation**: Updated `docs/README.md` with local testing references
+
+### 🧪 **Testing Infrastructure**
+- **ENHANCED: RuboCop Compliance**: Fixed all code style violations across test suite
+- **ENHANCED: Test Organization**: Improved test structure and mocking patterns
+- **ENHANCED: Integration Testing**: Better PostgreSQL integration test support
+- **ENHANCED: Security Auditing**: Bundle audit integration in CI pipeline
+
+### 🔧 **Configuration Files**
+- **NEW: `.actrc`**: Configuration for local GitHub Actions testing
+- **NEW: `.env.local.example`**: Template for local environment variables
+- **IMPROVED: `.gitignore`**: Added local testing files to ignore list
+
+## [0.2.1] - 2025-09-06
+
 ### 🚀 **Migration System Overhaul** 
 - **NEW: Automated Migration Management**: Complete migration system for multi-tenant schemas
 - **NEW: PgMultitenantSchemas::Migrator**: Comprehensive migration management class
@@ -94,3 +128,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release
 - Basic schema switching functionality
 - PostgreSQL multitenancy support
+
+[Unreleased]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/rubenpazch/pg_multitenant_schemas/releases/tag/v0.1.0

data/LOCAL_TESTING_SUMMARY.md

@@ -0,0 +1,141 @@
+# 🧪 Summary: How to Test GitHub Workflows Locally
+
+## ✅ What You Can Do Right Now
+
+### 1. **Pre-Push Script (Recommended)**## 📁 **Files Created**
+
+- **`pre-push-check.sh`** - Main testing script
+- **`validate-github-commands.sh`** - Test exact GitHub Actions commands
+- **`TESTING_LOCALLY.md`** - Quick start guide
+- **`docs/local_workflow_testing.md`** - Complete documentation
+- **`.actrc`** - act configuration
+- **`.env.local.example`** - Environment templateh
+# Run this before every push
+./pre-push-check.sh
+```
+This validates everything that runs in CI:
+- ✅ RuboCop (code style)
+- ✅ RSpec (tests)
+- ✅ Bundle audit (security)
+- ✅ Gem building
+- ✅ Integration tests (if PostgreSQL available)
+
+### 2. **Manual Component Testing**
+```bash
+```bash
+# Test each CI component individually
+bundle install
+bundle exec rubocop              # Code style check
+bundle exec rspec               # Run all tests
+bundle exec rspec --tag integration  # Integration tests only
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'  # Unit tests only
+bundle audit                    # Security audit
+gem build pg_multitenant_schemas.gemspec  # Test gem build
+```
+```
+
+### 3. **act Tool (Partial Support)**
+```bash
+# List workflows
+act -l
+
+# Dry run (shows what would execute)
+act -n push
+
+# Note: Currently has issues with PostgreSQL services
+# Better for simple workflows without database dependencies
+```
+
+## 🎯 **Before Every Push Checklist**
+
+1. ✅ Run `./pre-push-check.sh`
+2. ✅ Fix any issues found
+3. ✅ Commit your changes
+4. ✅ Push to GitHub
+
+## 📋 **Component Status**
+
+| Component | Local Testing | Status |
+|-----------|---------------|---------|
+| RuboCop | ✅ `bundle exec rubocop` | Working |
+| Unit Tests | ✅ `bundle exec rspec` | Working |
+| Integration Tests | ✅ With local PostgreSQL | Working |
+| Security Audit | ✅ `bundle audit` | Working |
+| Gem Building | ✅ `gem build *.gemspec` | Working |
+| Release Workflow | ⚠️ Manual simulation only | Partial |
+| Full CI with act | ⚠️ PostgreSQL service issues | Limited |
+
+## 🔧 **Quick Setup**
+
+1. **Make pre-push script executable:**
+   ```bash
+   chmod +x pre-push-check.sh
+   ```
+
+2. **Install act (optional):**
+   ```bash
+   brew install act
+   ```
+
+3. **Create environment file (for act):**
+   ```bash
+   cp .env.local.example .env.local
+   # Edit .env.local with your tokens if needed
+   ```
+
+## 🚀 **Recommended Workflow**
+
+```bash
+# 1. Make your changes
+git add .
+
+# 2. Test locally
+./pre-push-check.sh
+
+# 3. If all passes, commit and push
+git commit -m "Your changes"
+git push
+```
+
+## 🛠️ **Troubleshooting**
+
+### PostgreSQL Issues
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Start PostgreSQL (macOS)
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+```
+
+### Ruby Issues
+```bash
+# Install correct Ruby version
+rbenv install 3.3.0
+rbenv local 3.3.0
+bundle install
+```
+
+### act Issues
+```bash
+# Try without services (simpler)
+act -j security  # Just run security audit job
+
+# Check Docker is running
+docker ps
+```
+
+## 📚 **Files Created**
+
+- **`pre-push-check.sh`** - Main testing script
+- **`TESTING_LOCALLY.md`** - Quick start guide
+- **`docs/local_workflow_testing.md`** - Complete documentation
+- **`.actrc`** - act configuration
+- **`.env.local.example`** - Environment template
+
+---
+
+**💡 Bottom Line**: Use `./pre-push-check.sh` for reliable local testing. It covers 95% of what CI does and catches issues early!

data/TESTING_LOCALLY.md

@@ -0,0 +1,208 @@
+# 🚀 Quick Start: Testing GitHub Workflows Locally
+
+This guide gets you up and running quickly with local GitHub Actions testing.
+
+## 🎯 TL;DR - Quick Commands
+
+```bash
+# 1. Run pre-push checks (recommended before every push)
+./pre-push-check.sh
+
+# 2. Test GitHub Actions locally with act
+act -l                    # List all workflows
+act push                  # Test CI workflow
+act pull_request         # Test PR workflow
+
+# 3. Manual component testing
+bundle exec rubocop      # Code style check
+bundle exec rspec        # Run tests
+gem build *.gemspec     # Test gem building
+```
+
+## 🔧 One-Time Setup
+
+### 1. Install act (if not already installed)
+
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+### 2. Create local environment file
+
+```bash
+# Copy the example and fill in your values
+cp .env.local.example .env.local
+
+# Edit with your actual tokens (optional, only needed for release testing)
+nano .env.local
+```
+
+## 🧪 Testing Strategies
+
+### Strategy 1: Pre-Push Script (Recommended)
+
+Run this before every push:
+
+```bash
+./pre-push-check.sh
+```
+
+This runs:
+- ✅ RuboCop (code style)
+- ✅ RSpec (unit tests)  
+- ✅ Security audit
+- ✅ Gem build test
+- ✅ Integration tests (if PostgreSQL available)
+
+### Strategy 2: act - GitHub Actions Locally
+
+```bash
+# Test the main CI workflow
+act push
+
+# Test pull request workflow
+act pull_request
+
+# Dry run (see what would execute)
+act -n
+
+# Test specific job
+act -j test
+
+# List all available workflows and jobs
+act -l
+```
+
+### Strategy 3: Manual Component Testing
+
+```bash
+# Test each component individually
+bundle install
+bundle exec rubocop
+bundle exec rspec
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'  # Unit tests only
+bundle exec rspec --tag integration  # Integration tests only
+bundle audit
+gem build pg_multitenant_schemas.gemspec
+```
+
+## 🎯 Workflow-Specific Testing
+
+### Testing CI Workflow (.github/workflows/main.yml)
+
+```bash
+# With act
+act push
+
+# Manual simulation
+bundle install
+bundle exec rubocop
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'
+bundle audit
+```
+
+### Testing Release Workflow (.github/workflows/release.yml)
+
+```bash
+# With act (simulates main branch push)
+act push --env GITHUB_REF=refs/heads/main
+
+# Manual simulation (WITHOUT publishing)
+# 1. Update version in lib/pg_multitenant_schemas/version.rb
+# 2. Build gem locally
+gem build pg_multitenant_schemas.gemspec
+# 3. Check gem contents
+gem contents pg_multitenant_schemas-*.gem
+```
+
+## 🐛 Troubleshooting
+
+### act Issues
+
+```bash
+# Docker not running
+# → Start Docker Desktop
+
+# Permission denied
+# → Fix Docker permissions or use sudo
+
+# Platform issues
+act --container-architecture linux/amd64
+
+# Secrets not found
+# → Check .env.local file exists and has correct values
+```
+
+### PostgreSQL Issues
+
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Start PostgreSQL (macOS)
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+```
+
+### Ruby/Bundle Issues
+
+```bash
+# Install correct Ruby version
+rbenv install 3.3.0
+rbenv local 3.3.0
+
+# Clean and reinstall gems
+bundle clean --force
+bundle install
+```
+
+## 🔄 Typical Workflow
+
+1. **Make changes** to your code
+2. **Run pre-push checks**: `./pre-push-check.sh`
+3. **Fix any issues** found
+4. **Test with act** (optional): `act push`
+5. **Commit and push** when everything passes
+
+## 📋 Integration with Git
+
+Add to `.git/hooks/pre-push` to run checks automatically:
+
+```bash
+#!/bin/bash
+./pre-push-check.sh
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/pre-push
+```
+
+## 🎉 Success Indicators
+
+You're ready to push when you see:
+
+- ✅ Pre-push script passes all checks
+- ✅ `act push` completes without errors
+- ✅ All tests pass locally
+- ✅ RuboCop shows no violations
+- ✅ Gem builds successfully
+
+## 🔗 More Information
+
+- [Complete Guide](docs/local_workflow_testing.md) - Detailed documentation
+- [GitHub Actions Docs](https://docs.github.com/en/actions)
+- [act Documentation](https://github.com/nektos/act)
+
+---
+
+**💡 Pro Tip**: Run `./pre-push-check.sh` before every commit to catch issues early!

data/docs/README.md

@@ -15,6 +15,8 @@ This directory contains detailed documentation for each core component of the PG
 | **Errors** | Custom exception classes | [errors.md](errors.md) |
 | **Testing** | RSpec test suite and testing guide | [testing.md](testing.md) |
 | **Integration Testing** | PostgreSQL integration testing guide | [integration_testing.md](integration_testing.md) |
+| **CI/CD & Releases** | GitHub Actions automation setup | [github_actions_setup.md](github_actions_setup.md) |
+| **Local Workflow Testing** | Test GitHub Actions locally before push | [local_workflow_testing.md](local_workflow_testing.md) |
 
 ## 🏗️ Architecture Flow
 
@@ -60,7 +62,9 @@ Rails Application (executes in tenant schema)
 
 - **[Testing Guide](testing.md)**: Comprehensive RSpec test suite documentation
 - **[Integration Testing](integration_testing.md)**: PostgreSQL integration testing guide
+- **[Local Workflow Testing](local_workflow_testing.md)**: Test GitHub Actions locally before push
 - **Test Execution**: `bundle exec rspec` (unit tests) and `bundle exec rspec --tag integration` (integration tests)
+- **Pre-Push Testing**: `./pre-push-check.sh` (validates CI components locally)
 
 ## 🔍 Debug and Troubleshooting
 

data/docs/github_actions_permissions_fix.md

@@ -0,0 +1,136 @@
+# 🔧 Fixing GitHub Actions Permissions Issues
+
+## 🚨 Problem
+```
+remote: Permission to rubenpazch/pg_multitenant_schemas.git denied to github-actions[bot].
+fatal: unable to access 'https://github.com/rubenpazch/pg_multitenant_schemas/': The requested URL returned error: 403
+```
+
+## ✅ Solutions Applied
+
+### 1. Updated Release Workflow Permissions
+Added explicit permissions to `.github/workflows/release.yml`:
+```yaml
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+```
+
+### 2. Fixed GitHub Actions Bot Identity
+Changed Git configuration to use proper GitHub Actions bot identity:
+```yaml
+git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+git config --local user.name "github-actions[bot]"
+```
+
+## 🔧 Repository Settings to Check
+
+### On GitHub.com:
+
+1. **Go to your repository settings**
+   - Navigate to: `https://github.com/rubenpazch/pg_multitenant_schemas/settings`
+
+2. **Actions > General**
+   - Scroll down to "Workflow permissions"
+   - Select: **"Read and write permissions"**
+   - Check: **"Allow GitHub Actions to create and approve pull requests"**
+   - Click **Save**
+
+3. **Actions > General > Actions permissions**
+   - Ensure: **"Allow all actions and reusable workflows"** is selected
+   - Or at least: **"Allow actions created by GitHub"**
+
+## 🧪 Alternative Testing Approach
+
+If you want to test the release workflow without actual releases:
+
+### Create a Test Branch Release Workflow
+
+```yaml
+# .github/workflows/test-release.yml
+name: Test Release Workflow
+
+on:
+  workflow_dispatch:  # Manual trigger only
+  
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  test-release:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Test Git config
+        run: |
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          echo "Git config successful"
+          
+      - name: Test Git operations (dry run)
+        run: |
+          echo "Would create tag: v0.2.1"
+          echo "Would push to origin"
+          # Don't actually push in test
+          
+      - name: Test gem build
+        run: |
+          gem build pg_multitenant_schemas.gemspec
+          ls -la *.gem
+```
+
+## 🔍 Troubleshooting Steps
+
+### 1. Check Token Permissions
+```bash
+# In GitHub Actions, this should show the permissions
+echo "GITHUB_TOKEN permissions:"
+echo "Contents: ${{ github.token }}"
+```
+
+### 2. Verify Repository Access
+```bash
+# Test if the bot can access the repo
+git ls-remote origin
+```
+
+### 3. Check Branch Protection Rules
+- Go to Settings > Branches
+- Check if `main` branch has protection rules that block force pushes
+- Ensure "Restrict pushes that create files" is not enabled
+
+## 🎯 Quick Fix Summary
+
+1. **✅ Updated workflow permissions** (already done)
+2. **✅ Fixed bot identity** (already done)
+3. **🔧 Check repository settings** (manual step on GitHub.com)
+4. **🧪 Test with manual trigger** (if needed)
+
+## 📋 Manual Steps Required
+
+1. Go to your repository on GitHub.com
+2. Navigate to Settings > Actions > General
+3. Set "Workflow permissions" to "Read and write permissions"
+4. Enable "Allow GitHub Actions to create and approve pull requests"
+5. Save the settings
+
+After making these changes, the release workflow should work properly!
+
+## 🚀 Testing the Fix
+
+After updating repository settings, you can test by:
+
+1. **Making a small version bump**
+2. **Pushing to main branch**  
+3. **Watching the Actions tab** for successful execution
+
+Or create the test workflow above and trigger it manually first.

data/docs/github_actions_setup.md

@@ -0,0 +1,181 @@
+# GitHub Actions Setup Guide
+
+This document explains how to set up GitHub Actions for automated testing and releases.
+
+## Overview
+
+The repository uses two main workflows:
+
+1. **CI Workflow** (`.github/workflows/main.yml`) - Runs tests on every push and PR
+2. **Release Workflow** (`.github/workflows/release.yml`) - Automatically releases to RubyGems when version changes
+
+## Setting Up RubyGems API Key
+
+To enable automatic releases to RubyGems, you need to set up a GitHub secret with your RubyGems API key.
+
+### Step 1: Get Your RubyGems API Key
+
+1. Go to [RubyGems.org](https://rubygems.org/)
+2. Sign in to your account
+3. Go to your profile settings
+4. Navigate to "API Keys" section
+5. Create a new API key or use an existing one
+6. Copy the API key (it should start with `rubygems_`)
+
+### Step 2: Add GitHub Secret
+
+1. Go to your GitHub repository
+2. Click on "Settings" tab
+3. In the left sidebar, click "Secrets and variables" → "Actions"
+4. Click "New repository secret"
+5. Name: `RUBYGEMS_API_KEY`
+6. Value: Paste your RubyGems API key
+7. Click "Add secret"
+
+### 3. Configure Repository Permissions
+
+**Important:** Configure GitHub Actions permissions to allow the release workflow to create tags and releases:
+
+1. Go to your repository Settings
+2. Navigate to **Actions > General**
+3. Under "Workflow permissions":
+   - Select **"Read and write permissions"**
+   - Check **"Allow GitHub Actions to create and approve pull requests"**
+4. Click **Save**
+
+Without these permissions, you'll get errors like:
+```
+remote: Permission to username/repo.git denied to github-actions[bot].
+fatal: unable to access 'https://github.com/username/repo/': The requested URL returned error: 403
+```
+
+## How the Workflows Work
+
+### CI Workflow
+
+**Triggers:**
+- Every push to `main` branch
+- Every pull request to `main` branch
+
+**What it does:**
+- Tests on Ruby 3.2, 3.3, and 3.4
+- Runs RuboCop for code quality
+- Runs unit tests (excluding integration tests)
+- Runs integration tests (with PostgreSQL database)
+- Runs security audit with bundle-audit
+
+### Release Workflow
+
+**Triggers:**
+- Push to `main` branch that changes `lib/pg_multitenant_schemas/version.rb`
+
+**What it does:**
+- Checks if the version in `version.rb` has changed
+- If version changed:
+  1. Builds the gem
+  2. Creates a Git tag (e.g., `v0.2.1`)
+  3. Creates a GitHub release with changelog notes
+  4. Publishes the gem to RubyGems
+
+## Release Process
+
+To release a new version:
+
+1. **Update the version** in `lib/pg_multitenant_schemas/version.rb`:
+   ```ruby
+   module PgMultitenantSchemas
+     VERSION = "0.2.1"  # Increment this
+   end
+   ```
+
+2. **Update the changelog** in `CHANGELOG.md`:
+   ```markdown
+   ## [0.2.1] - 2025-09-07
+   
+   ### Added
+   - New feature description
+   
+   ### Fixed
+   - Bug fix description
+   ```
+
+3. **Commit and push** to main branch:
+   ```bash
+   git add lib/pg_multitenant_schemas/version.rb CHANGELOG.md
+   git commit -m "Bump version to 0.2.1"
+   git push origin main
+   ```
+
+4. **Automatic release** will trigger:
+   - GitHub Actions will detect the version change
+   - Create a Git tag and GitHub release
+   - Publish to RubyGems automatically
+
+## Manual Release (Alternative)
+
+If you prefer manual releases or need to troubleshoot:
+
+```bash
+# Build the gem
+gem build pg_multitenant_schemas.gemspec
+
+# Push to RubyGems (requires authentication)
+gem push pg_multitenant_schemas-0.2.1.gem
+
+# Create Git tag
+git tag v0.2.1
+git push origin v0.2.1
+```
+
+## Workflow Status
+
+You can monitor workflow runs:
+
+1. Go to your GitHub repository
+2. Click the "Actions" tab
+3. View running and completed workflows
+4. Click on individual runs to see detailed logs
+
+## Security Considerations
+
+- **API Keys**: Never commit API keys to the repository
+- **Secrets**: Use GitHub Secrets for sensitive information
+- **Permissions**: The `GITHUB_TOKEN` has limited permissions for creating releases
+- **Audit**: The security workflow checks for vulnerable dependencies
+
+## Troubleshooting
+
+### Common Issues
+
+1. **RubyGems authentication failed**
+   - Check that `RUBYGEMS_API_KEY` secret is set correctly
+   - Ensure the API key has publishing permissions
+
+2. **Git tag already exists**
+   - The workflow checks for existing tags
+   - If tag exists, release is skipped
+
+3. **Tests failing**
+   - CI must pass before release workflow runs
+   - Check test logs in the Actions tab
+
+4. **PostgreSQL connection issues**
+   - Integration tests require PostgreSQL service
+   - Check service configuration in workflow
+
+### Debug Steps
+
+1. Check workflow logs in GitHub Actions
+2. Verify secrets are set correctly
+3. Test locally with same Ruby versions
+4. Check RubyGems.org for published gems
+
+## Best Practices
+
+1. **Version Bumping**: Use semantic versioning (MAJOR.MINOR.PATCH)
+2. **Changelog**: Always update changelog before releasing
+3. **Testing**: Ensure all tests pass locally before pushing
+4. **Security**: Regularly update dependencies and run security audits
+5. **Documentation**: Update documentation for breaking changes
+
+This automated setup ensures consistent, reliable releases while maintaining code quality through comprehensive testing.

data/docs/local_workflow_testing.md

@@ -0,0 +1,314 @@
+# Testing GitHub Workflows Locally
+
+This guide shows you how to test GitHub Actions workflows locally before pushing to GitHub.
+
+## 🚀 Method 1: Using `act` (Recommended)
+
+`act` is the most popular tool for running GitHub Actions locally using Docker.
+
+### Installation
+
+```bash
+# macOS (using Homebrew)
+brew install act
+
+# Linux (using curl)
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows (using Chocolatey)
+choco install act-cli
+```
+
+### Basic Usage
+
+```bash
+# List all workflows
+act -l
+
+# Run all workflows
+act
+
+# Run specific workflow
+act push
+
+# Run specific job
+act -j test
+
+# Run with specific event
+act pull_request
+
+# Dry run (show what would be executed)
+act -n
+```
+
+### Testing Our Workflows
+
+```bash
+# Test the main CI workflow
+act push
+
+# Test the release workflow (simulates a push to main)
+act push --env GITHUB_REF=refs/heads/main
+
+# Test pull request workflow
+act pull_request
+```
+
+### Configuration
+
+Create `.actrc` file in project root for default settings:
+
+```bash
+# .actrc
+--container-architecture linux/amd64
+--artifact-server-path /tmp/act-artifacts
+--env-file .env.local
+```
+
+### Environment Variables
+
+Create `.env.local` for local testing:
+
+```bash
+# .env.local
+GITHUB_TOKEN=your_github_token_here
+RUBYGEMS_API_KEY=your_rubygems_key_here
+GITHUB_REPOSITORY=rubenpazch/pg_multitenant_schemas
+GITHUB_ACTOR=your_username
+```
+
+## 🔧 Method 2: Manual Testing Components
+
+### Test RuboCop Locally
+
+```bash
+# Run RuboCop (same as in CI)
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -A
+
+# Check specific files
+bundle exec rubocop lib/ spec/
+```
+
+### Test RSpec Locally
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage (if configured)
+COVERAGE=true bundle exec rspec
+
+# Run integration tests
+bundle exec rspec --tag integration
+
+# Run tests with different Ruby versions (using rbenv/rvm)
+rbenv shell 3.2.0 && bundle exec rspec
+rbenv shell 3.3.0 && bundle exec rspec
+```
+
+### Test Gem Building
+
+```bash
+# Build gem locally
+gem build pg_multitenant_schemas.gemspec
+
+# Install locally built gem
+gem install pg_multitenant_schemas-*.gem
+
+# Test gem installation
+gem list | grep pg_multitenant_schemas
+```
+
+### Test PostgreSQL Setup
+
+```bash
+# Start PostgreSQL (macOS with Homebrew)
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+
+# Run integration tests
+PGDATABASE=pg_multitenant_test bundle exec rspec --tag integration
+```
+
+## 🐳 Method 3: Docker-based Testing
+
+Create a local testing environment that mirrors CI:
+
+```bash
+# Create Dockerfile.test
+cat > Dockerfile.test << 'EOF'
+FROM ruby:3.3
+
+# Install PostgreSQL client
+RUN apt-get update && apt-get install -y postgresql-client
+
+# Set working directory
+WORKDIR /app
+
+# Copy Gemfile
+COPY Gemfile* ./
+RUN bundle install
+
+# Copy source code
+COPY . .
+
+# Run tests
+CMD ["bundle", "exec", "rspec"]
+EOF
+
+# Build and run
+docker build -f Dockerfile.test -t pg_multitenant_test .
+docker run --rm pg_multitenant_test
+```
+
+## 🔍 Method 4: GitHub CLI for Remote Testing
+
+Use GitHub CLI to trigger workflows manually:
+
+```bash
+# Install GitHub CLI
+brew install gh
+
+# Authenticate
+gh auth login
+
+# Trigger workflow manually
+gh workflow run main.yml
+
+# Check workflow status
+gh run list
+
+# View workflow logs
+gh run view --log
+```
+
+## 📋 Pre-Push Checklist
+
+Before pushing to GitHub, run these commands locally:
+
+```bash
+#!/bin/bash
+# pre-push-check.sh
+
+echo "🔍 Running pre-push checks..."
+
+# 1. RuboCop
+echo "Running RuboCop..."
+bundle exec rubocop || exit 1
+
+# 2. RSpec
+echo "Running RSpec..."
+bundle exec rspec || exit 1
+
+# 3. Security audit
+echo "Running security audit..."
+bundle audit || exit 1
+
+# 4. Gem build test
+echo "Testing gem build..."
+gem build pg_multitenant_schemas.gemspec || exit 1
+
+# 5. Integration tests (if PostgreSQL available)
+if command -v psql &> /dev/null; then
+    echo "Running integration tests..."
+    bundle exec rspec --tag integration || exit 1
+fi
+
+echo "✅ All checks passed! Ready to push."
+```
+
+Make it executable:
+
+```bash
+chmod +x pre-push-check.sh
+./pre-push-check.sh
+```
+
+## 🎯 Specific Workflow Testing
+
+### Testing CI Workflow (main.yml)
+
+```bash
+# Using act
+act push -W .github/workflows/main.yml
+
+```bash
+# Manual simulation
+bundle install
+bundle exec rubocop
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'
+bundle audit
+```
+```
+
+### Testing Release Workflow (release.yml)
+
+```bash
+# Simulate version bump
+# 1. Update version in lib/pg_multitenant_schemas/version.rb
+# 2. Test locally
+act push -W .github/workflows/release.yml --env GITHUB_REF=refs/heads/main
+
+# Manual simulation (without actual publishing)
+gem build pg_multitenant_schemas.gemspec
+# Note: Don't run 'gem push' in testing
+```
+
+## 🛠️ Troubleshooting
+
+### Common Issues with `act`
+
+1. **Docker not running**: Start Docker Desktop
+2. **Permission issues**: Run with `sudo` or fix Docker permissions
+3. **Platform issues**: Use `--container-architecture linux/amd64`
+4. **Secret errors**: Provide secrets via `.env.local` file
+
+### PostgreSQL Issues
+
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Start PostgreSQL service
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+```
+
+### Ruby Version Issues
+
+```bash
+# Install required Ruby versions
+rbenv install 3.2.0
+rbenv install 3.3.0
+rbenv install 3.4.0
+
+# Test with specific version
+rbenv shell 3.3.0
+bundle install
+bundle exec rspec
+```
+
+## 📚 Additional Resources
+
+- [act Documentation](https://github.com/nektos/act)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Local Development Best Practices](https://docs.github.com/en/actions/using-workflows/about-workflows#best-practices)
+
+## 🔗 Integration with Git Hooks
+
+Add to `.git/hooks/pre-push`:
+
+```bash
+#!/bin/bash
+./pre-push-check.sh
+exit $?
+```
+
+This ensures checks run automatically before every push.

data/lib/pg_multitenant_schemas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgMultitenantSchemas
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/pre-push-check.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# Pre-push check script for pg_multitenant_schemas gem
+# Run this before pushing to GitHub to catch issues early
+
+set -e  # Exit on any error
+
+echo "🔍 Running pre-push checks for pg_multitenant_schemas..."
+echo ""
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_status() {
+    echo -e "${2}${1}${NC}"
+}
+
+# Function to run a check
+run_check() {
+    local name="$1"
+    local command="$2"
+    local optional="$3"
+    
+    echo "📋 $name..."
+    if eval "$command"; then
+        print_status "✅ $name passed" "$GREEN"
+    else
+        if [ "$optional" = "true" ]; then
+            print_status "⚠️  $name failed (optional)" "$YELLOW"
+        else
+            print_status "❌ $name failed" "$RED"
+            exit 1
+        fi
+    fi
+    echo ""
+}
+
+# 1. Check if we're in the right directory
+if [ ! -f "pg_multitenant_schemas.gemspec" ]; then
+    print_status "❌ Not in pg_multitenant_schemas directory" "$RED"
+    exit 1
+fi
+
+# 2. Install dependencies
+run_check "Bundle install" "bundle install --quiet"
+
+# 3. RuboCop
+run_check "RuboCop (code style)" "bundle exec rubocop"
+
+# 4. RSpec unit tests
+run_check "RSpec unit tests" "bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'"
+
+# 5. Security audit
+run_check "Security audit" "bundle audit" "true"
+
+# 6. Gem build test
+run_check "Gem build test" "gem build pg_multitenant_schemas.gemspec > /dev/null 2>&1 && rm -f pg_multitenant_schemas-*.gem"
+
+# 7. Check for PostgreSQL and run integration tests
+if command -v psql &> /dev/null && pg_isready &> /dev/null; then
+    # Check if test database exists, create if not
+    if ! psql -lqt | cut -d \| -f 1 | grep -qw pg_multitenant_test; then
+        echo "📋 Creating test database..."
+        createdb pg_multitenant_test || true
+    fi
+    
+    run_check "Integration tests" "PGDATABASE=pg_multitenant_test bundle exec rspec --tag integration" "true"
+else
+    print_status "⚠️  PostgreSQL not available, skipping integration tests" "$YELLOW"
+fi
+
+# 8. Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+    print_status "⚠️  You have uncommitted changes" "$YELLOW"
+    git status --short
+    echo ""
+fi
+
+# 9. Check current branch
+current_branch=$(git branch --show-current)
+if [ "$current_branch" = "main" ]; then
+    print_status "⚠️  You're on the main branch" "$YELLOW"
+fi
+
+echo "🎉 All checks completed successfully!"
+echo ""
+echo "🚀 Your code is ready to push to GitHub!"
+echo ""
+echo "💡 Pro tip: You can test GitHub Actions locally using 'act':"
+echo "   brew install act"
+echo "   act push  # Test CI workflow"
+echo ""

data/test-github-setup.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Test GitHub Actions permissions and setup locally
+
+echo "🔍 Testing GitHub Actions setup and permissions..."
+echo ""
+
+# Check if we're in a Git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "❌ Not in a Git repository"
+    exit 1
+fi
+
+# Check if we're on the right branch
+current_branch=$(git branch --show-current)
+echo "📋 Current branch: $current_branch"
+
+# Check if we have the workflow files
+if [ -f ".github/workflows/main.yml" ]; then
+    echo "✅ CI workflow file exists"
+else
+    echo "❌ CI workflow file missing"
+fi
+
+if [ -f ".github/workflows/release.yml" ]; then
+    echo "✅ Release workflow file exists"
+else
+    echo "❌ Release workflow file missing"
+fi
+
+# Check version file
+if [ -f "lib/pg_multitenant_schemas/version.rb" ]; then
+    version=$(grep -E "VERSION = ['\"]" lib/pg_multitenant_schemas/version.rb | cut -d'"' -f2 | cut -d"'" -f2)
+    echo "✅ Version file exists: $version"
+else
+    echo "❌ Version file missing"
+fi
+
+# Check if gemspec exists
+if [ -f "pg_multitenant_schemas.gemspec" ]; then
+    echo "✅ Gemspec file exists"
+else
+    echo "❌ Gemspec file missing"
+fi
+
+# Check remote origin
+remote_url=$(git remote get-url origin 2>/dev/null || echo "No remote")
+echo "📋 Remote origin: $remote_url"
+
+# Test Git config (what GitHub Actions would use)
+echo ""
+echo "🧪 Testing Git configuration..."
+git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+git config --local user.name "github-actions[bot]"
+echo "✅ Git config set for GitHub Actions bot"
+
+# Test gem build
+echo ""
+echo "🧪 Testing gem build..."
+if gem build pg_multitenant_schemas.gemspec > /dev/null 2>&1; then
+    echo "✅ Gem builds successfully"
+    rm -f pg_multitenant_schemas-*.gem
+else
+    echo "❌ Gem build failed"
+fi
+
+# Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+    echo ""
+    echo "⚠️  You have uncommitted changes:"
+    git status --short
+fi
+
+echo ""
+echo "🎯 Next Steps:"
+echo "1. Ensure repository has proper permissions set in GitHub:"
+echo "   - Go to Settings > Actions > General"
+echo "   - Set 'Workflow permissions' to 'Read and write permissions'"
+echo "   - Enable 'Allow GitHub Actions to create and approve pull requests'"
+echo ""
+echo "2. To trigger a release:"
+echo "   - Update version in lib/pg_multitenant_schemas/version.rb"
+echo "   - Commit and push to main branch"
+echo "   - GitHub Actions will automatically create a release"
+echo ""
+echo "📚 For more details, see: docs/github_actions_setup.md"

data/validate-github-commands.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Validate GitHub workflow commands locally
+# This script tests the exact commands used in GitHub Actions
+
+set -e
+
+echo "🧪 Testing GitHub Actions commands locally..."
+echo ""
+
+# Test RuboCop (exact command from workflow)
+echo "📋 Testing: bundle exec rubocop"
+if bundle exec rubocop > /dev/null 2>&1; then
+    echo "✅ RuboCop passed"
+else
+    echo "❌ RuboCop failed"
+    exit 1
+fi
+
+# Test unit tests (exact command from workflow) 
+echo "📋 Testing: bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'"
+if bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb' > /dev/null 2>&1; then
+    echo "✅ Unit tests passed"
+else
+    echo "❌ Unit tests failed"
+    exit 1
+fi
+
+# Test integration tests (exact command from workflow)
+echo "📋 Testing: bundle exec rspec --tag integration"
+if bundle exec rspec --tag integration > /dev/null 2>&1; then
+    echo "✅ Integration tests passed"
+else
+    echo "⚠️  Integration tests failed (may need PostgreSQL setup)"
+fi
+
+# Test security audit (exact command from workflow)
+echo "📋 Testing: bundle audit"
+if bundle audit > /dev/null 2>&1; then
+    echo "✅ Security audit passed"
+else
+    echo "⚠️  Security audit failed (may have vulnerabilities)"
+fi
+
+echo ""
+echo "🎉 GitHub Actions command validation complete!"
+echo ""
+echo "💡 These are the exact commands that run in GitHub Actions CI"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_multitenant_schemas
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Ruben Paz
@@ -73,6 +73,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".actrc"
+- ".env.local.example"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_simple.yml"
@@ -80,13 +82,18 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
+- LOCAL_TESTING_SUMMARY.md
 - README.md
 - Rakefile
+- TESTING_LOCALLY.md
 - docs/README.md
 - docs/configuration.md
 - docs/context.md
 - docs/errors.md
+- docs/github_actions_permissions_fix.md
+- docs/github_actions_setup.md
 - docs/integration_testing.md
+- docs/local_workflow_testing.md
 - docs/migrator.md
 - docs/rails_integration.md
 - docs/schema_switcher.md
@@ -117,9 +124,12 @@ files:
 - lib/pg_multitenant_schemas/tenant_task_helpers.rb
 - lib/pg_multitenant_schemas/version.rb
 - pg_multitenant_schemas.gemspec
+- pre-push-check.sh
 - rails_integration/app/controllers/application_controller.rb
 - rails_integration/app/models/tenant.rb
 - sig/pg_multitenant_schemas.rbs
+- test-github-setup.sh
+- validate-github-commands.sh
 homepage: https://github.com/rubenpazch/pg_multitenant_schemas
 licenses:
 - MIT