Skip to main content
The Spoo.me Setup Action is a reusable GitHub Action that automatically configures the complete spoo.me URL shortener service within any GitHub Actions workflow. This action eliminates the complexity of manually setting up MongoDB, Redis, Python dependencies, and the spoo.me service itself.

GitHub Marketplace

View the action on GitHub Marketplace

​
Features

Complete Environment

Automatically installs and configures Python, MongoDB, and Redis

Service Management

Clones spoo.me repository and starts service in background

Health Monitoring

Verifies all services are running before proceeding

Highly Configurable

Custom versions for Python, MongoDB, and Redis

​
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@v1
        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.service-url }}

​
Configuration

​
Inputs

​
python-version
string
default:"3.11"
Python version to install. Recommended: 3.11 or higher for best compatibility.
​
mongodb-version
string
default:"7.0"
MongoDB version to use. Supports versions 6.0 and higher.
​
redis-version
string
default:"7.2"
Redis version to use for caching and session management.
​
spoo-directory
string
default:"spoo-me"
Directory name where the spoo.me repository will be cloned.
​
wait-timeout
string
default:"120"
Timeout in seconds to wait for all services to be ready. Increase for slower environments.

​
Outputs

​
service-url
string
URL where the spoo.me service is running (typically http://127.0.0.1:8000)
​
mongodb-uri
string
MongoDB connection URI for direct database access
​
redis-uri
string
Redis connection URI for cache operations
Accessible via: steps.<spoo-setup-step-id>.outputs.<output-id>

​
Usage Examples

​
Integration Testing

1

Set up the workflow

Create a workflow file that sets up spoo.me and runs your integration tests.
.github/workflows/integration.yml
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@v1
        id: spoo
        
      - name: Test URL shortening API
        run: |
          # Test the shortening endpoint
          response=$(curl -s -X POST \
            -H "Content-Type: application/json" \
            -d '{"url": "https://example.com"}' \
            ${{ steps.spoo.outputs.service-url }}/api/shorten)
          echo "API Response: $response"
The service will be available at the URL provided in the service-url output.
2

Add comprehensive tests

Use the running service to test all your integration scenarios.
      - name: Test analytics endpoint
        run: |
          # Test analytics after creating a short URL
          curl -s ${{ steps.spoo.outputs.service-url }}/api/analytics
          
      - name: Test error handling
        run: |
          # Test invalid URL handling
          curl -s -X POST \
            -H "Content-Type: application/json" \
            -d '{"url": "invalid-url"}' \
            ${{ steps.spoo.outputs.service-url }}/api/shorten

​
Multi-Version Testing

Test your application against multiple versions of dependencies: 
name: Multi-Version Test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.11', '3.12']
        mongodb-version: ['6.0', '7.0']
        
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Spoo.me
        uses: spoo-me/setup-action@v1
        with:
          python-version: ${{ matrix.python-version }}
          mongodb-version: ${{ matrix.mongodb-version }}
          
      - name: Run compatibility tests
        run: |
          echo "Testing Python ${{ matrix.python-version }} with MongoDB ${{ matrix.mongodb-version }}"
          # Your tests here

​
Environment Configuration

The action automatically configures these environment variables: 
# MongoDB connection (optimized single instance)
MONGODB_URI=mongodb://localhost:27017/url-shortener
MONGODB_URI_DEV=mongodb://localhost:27017/url-shortener
MONGO_DB_NAME=url-shortener

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

# Flask application settings
SECRET_KEY=github-action-secret-key-for-testing
HOST_URI=127.0.0.1:8000
SHORTEN_API_RATE_LIMIT_PER_HOUR=100

# Webhook settings (empty for local testing)
CONTACT_WEBHOOK=
URL_REPORT_WEBHOOK=
HCAPTCHA_SECRET=

​
How It Works

The action performs these steps automatically:
1

Environment Setup

Installs Python, MongoDB, and Redis with specified versions
2

Service Verification

Verifies all databases are accessible and responsive
3

Repository Setup

Clones the spoo.me repository and installs dependencies using UV
4

Database Initialization

Creates necessary collections and indexes for optimal performance
5

Service Launch

Starts the spoo.me service in the background with health checks
6

Ready State

Outputs service URLs and confirms all systems are operational

​
Troubleshooting

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
Increase the wait-timeout value to 180 seconds or higher for slower environments.
The action includes built-in retry logic, but if issues persist:
  • Increase the wait-timeout value to 180 or higher
  • Check for port conflicts (MongoDB: 27017, Redis: 6379, Service: 8000)
  • Verify the GitHub Actions runner has sufficient resources
MongoDB startup can be slow on some runners. We’ve optimized this with single-instance setup.
The action uses standard ports:
  • MongoDB: 27017
  • Redis: 6379
  • Spoo.me Service: 8000
If you have conflicts, ensure no other services are using these ports in your workflow.

​
Versioning

The action follows semantic versioning. Use @v1 for automatic updates within the major version, or pin to specific versions for maximum stability.