Spoo.me Setup Action

A reusable GitHub Action to run the spoo.me URL shortener locally in CI 🚀

🚀 Quick Start ⚙️ Inputs 📤 Outputs 📚 Examples 🐛 Troubleshooting

⚡ Introduction

A reusable GitHub Action that automatically sets up the spoo.me URL shortener service locally within any GitHub Actions workflow. This action handles all the complexity of setting up MongoDB, Redis, Python dependencies, and the FastAPI service itself.

🔥 Features

• Reusable - Use in any repository with uses: spoo-me/setup-action@v2 🔄
• Complete Environment - Automatically installs and configures Python, MongoDB, and Redis ⚡
• FastAPI + Uvicorn - Starts the service with uvicorn for production-grade performance 🚀
• Health Monitoring - Verifies all services via the /health endpoint before proceeding 🔍
• Configurable - Supports custom versions for Python, MongoDB, and Redis ⚙️
• Fast Startup - Optimized MongoDB setup (single instance, not replica set) ⚡
• Clean Integration - Easy to integrate into existing workflows as a single step 🎯

🚀 Quick Start

Basic Usage

name: Test with Spoo.me Service

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Spoo.me Service
        uses: spoo-me/setup-action@v2
        id: spoo-setup

      - name: Run tests against Spoo.me
        run: |
          echo "Service running at: ${{ steps.spoo-setup.outputs.service-url }}"
          curl -s ${{ steps.spoo-setup.outputs.health-url }}

Advanced Usage with Custom Configuration

name: Integration Tests

on: [push]

jobs:
  integration-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Spoo.me Service
        uses: spoo-me/setup-action@v2
        id: spoo-setup
        with:
          python-version: '3.13'
          mongodb-version: '7.0'
          redis-version: '7.2'
          spoo-directory: 'my-spoo-instance'
          wait-timeout: '180'

      - name: Test URL shortening API
        run: |
          echo "Testing against: ${{ steps.spoo-setup.outputs.service-url }}"
          echo "Health: ${{ steps.spoo-setup.outputs.health-url }}"
          echo "MongoDB: ${{ steps.spoo-setup.outputs.mongodb-uri }}"
          echo "Redis: ${{ steps.spoo-setup.outputs.redis-uri }}"

⚙️ Inputs

Input	Description	Required	Default
python-version	Python version to install	No	3.13
mongodb-version	MongoDB version to use	No	7.0
redis-version	Redis version to use	No	7.2
spoo-directory	Directory to clone spoo.me repository	No	spoo-me
wait-timeout	Timeout in seconds to wait for services	No	120

📤 Outputs

Output	Description	Example
service-url	URL where the spoo.me service is running	http://127.0.0.1:8000
health-url	URL for the health check endpoint	http://127.0.0.1:8000/health
mongodb-uri	MongoDB connection URI (includes database name)	mongodb://localhost:27017/url-shortener
redis-uri	Redis connection URI	redis://localhost:6379

🔧 Environment Configuration

The action automatically configures the following environment variables for the spoo.me service:

# MongoDB connection details
MONGODB_URI=mongodb://localhost:27017/
DB_NAME=url-shortener

# Redis connection details
REDIS_URI=redis://localhost:6379
REDIS_TTL_SECONDS=3600

# App configs
SECRET_KEY=<auto-generated>
HOST_URI=127.0.0.1:8000
ENV=development
APP_URL=http://127.0.0.1:8000

# JWT (HS256 mode — no RSA keys needed in CI)
JWT_SECRET=<auto-generated>
JWT_ISSUER=spoo.me
JWT_AUDIENCE=spoo.me.api
COOKIE_SECURE=false

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=console

# Disabled in CI: Sentry, OAuth, Email, hCaptcha

Note

SECRET_KEY and JWT_SECRET are randomly generated at setup time. OAuth, Sentry, and email are left unconfigured — the app runs fine without them.

📊 What the Action Does

1. 🐍 Python Setup - Installs the specified Python version
2. 🍃 MongoDB Setup - Starts optimized single-instance MongoDB (faster than replica sets)
3. 🔴 Redis Setup - Starts Redis service on the default port
4. ✅ Service Verification - Verifies both databases are accessible
5. 📦 Repository Cloning - Clones the spoo.me URL shortener repository
6. 🚀 UV Installation - Installs uv for fast Python package management
7. ⚙️ Environment Configuration - Sets up all required environment variables
8. 📦 Dependency Installation - Installs Python dependencies using uv sync
9. 🌐 Service Startup - Starts the FastAPI service with uvicorn in the background
10. 🔍 Health Checks - Verifies the service is running via GET /health

📚 Usage Examples

Integration Testing

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Spoo.me
        uses: spoo-me/setup-action@v2
        id: spoo

      - name: Run integration tests
        run: |
          # Test URL shortening
          response=$(curl -s -X POST \
            -H "Content-Type: application/x-www-form-urlencoded" \
            -d "url=https://example.com" \
            ${{ steps.spoo.outputs.service-url }}/)
          echo "API Response: $response"

Multi-Version Testing

name: Multi-Version Test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.12', '3.13']
        mongodb-version: ['7.0', '8.0']

    steps:
      - uses: actions/checkout@v4

      - name: Setup Spoo.me
        uses: spoo-me/setup-action@v2
        with:
          python-version: ${{ matrix.python-version }}
          mongodb-version: ${{ matrix.mongodb-version }}

Load Testing

name: Load Testing

on: workflow_dispatch

jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Spoo.me
        uses: spoo-me/setup-action@v2
        with:
          wait-timeout: '300'
        id: spoo

      - name: Install Apache Bench
        run: sudo apt-get update && sudo apt-get install -y apache2-utils

      - name: Run load test
        run: |
          echo "Running load test against ${{ steps.spoo.outputs.service-url }}"
          ab -n 1000 -c 10 ${{ steps.spoo.outputs.service-url }}/

🐛 Troubleshooting

Service Not Starting

If the service fails to start, check the logs:

- name: Check service logs
  if: failure()
  run: |
    cd spoo-me  # or your custom directory
    cat spoo-service.log

Health Check Returns "degraded"

This means MongoDB is fine but Redis isn't connected. The service still works — Redis is optional for caching. Check:

- name: Check health
  run: curl -s http://127.0.0.1:8000/health | python3 -m json.tool

Common Issues

• Timeout errors: Increase wait-timeout to 180 or higher
• Port conflicts: The action uses standard ports (27017 for MongoDB, 6379 for Redis, 8000 for the service)
• Python version compatibility: Use Python 3.12 or higher for best compatibility
• MongoDB slow startup: Uses single instance (not replica set) for faster startup

🗂️ Repository Structure

setup-action/
├── action.yml                     # Main action definition
├── README.md                      # This documentation
├── USAGE.md                       # Quick usage guide
├── LICENSE                        # Apache 2.0 License
├── SECURITY.md                    # Security policy
├── CODE_OF_CONDUCT.md             # Code of conduct
└── .github/
    └── workflows/
        └── test.yml               # Comprehensive test workflow

🔄 Versioning

This action follows semantic versioning. Available versions:

• @v2 - Latest stable v2.x release (recommended)
• @v2.0.0 - Specific version
• @v1 - Legacy (Flask-based spoo.me)
• @main - Latest development version (not recommended for production)

🤝 Contributing

Contributions are always welcome! 🎉 Here's how you can contribute:

• Bugs are logged using the github issue system. To report a bug, simply open a new issue.
• Make a pull request for any feature or bug fix.

Important

For any type of support or queries, feel free to reach out to us at ✉️ support@spoo.me

🙏 Acknowledgments

• Spoo.me URL Shortener - The amazing URL shortening service
• Supercharge MongoDB Action - MongoDB setup
• Supercharge Redis Action - Redis setup
• UV - Fast Python package management

---

© spoo.me . 2026

All Rights Reserved