Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/surqo/llms.txt

Use this file to discover all available pages before exploring further.

Surqo uses a GitHub Actions pipeline defined in .github/workflows/ci-cd.yml that runs on every push and pull request targeting master or main. The pipeline has two jobs: a test job that lints and runs the full test suite (fires on both pushes and PRs), and a deploy-backend job that deploys to Fly.io (fires only on push to master). Frontend deploys are handled automatically by Vercel’s GitHub Integration and require no additional pipeline configuration.

​
Pipeline Overview

push to master/main / PR to master/main
        │
        ▼
   ┌─────────┐
   │  test   │  Ubuntu · Python 3.11 · uv sync --dev
   │         │  ruff check app/
   │         │  pytest --cov (SQLite in-memory)
   └────┬────┘
        │ success (push to master only)
        ▼
┌──────────────────┐
│  deploy-backend  │  flyctl deploy --remote-only
└──────────────────┘

Frontend: Vercel GitHub Integration
          Preview deployments on every PR
          Production deploy on merge to master

​
Required GitHub Secrets

Before the pipeline can run successfully, add the following secrets to your GitHub repository under Settings → Secrets and variables → Actions.
Secret NameDescription
GROQ_API_KEYGroq API key for LLM calls (gsk_...)
ANTHROPIC_API_KEYAnthropic API key — optional fallback
SUPABASE_URLSupabase project URL (https://xxx.supabase.co)
SUPABASE_KEYSupabase service role key
FLY_API_TOKENFly.io deploy token (see below)
If GROQ_API_KEY or ANTHROPIC_API_KEY are not set, the workflow falls back to safe placeholder values for the test job (e.g. GROQ_API_KEY defaults to 'test_key', SUPABASE_URL to a placeholder URL). The deploy-backend job will fail if FLY_API_TOKEN is missing. Other runtime secrets (Redis, HiveMQ, Resend, etc.) are hardcoded to test-safe values directly in the workflow and do not need to be set as GitHub Secrets.

​
Test Job

The test job runs on ubuntu-latest with its working directory set to backend/. It uses astral-sh/setup-uv@v3 to install Python 3.11 and uv in a single step, avoiding the separate actions/setup-python action. 
# Install all dependencies including dev tools (ruff, pytest, pytest-cov)
uv sync --dev

# Lint — fails the job on any ruff violation
uv run ruff check app/

# Run the full test suite with coverage
uv run pytest tests/ --cov=app --cov-report=term-missing -v
The test job injects a minimal environment so tests run without real external services:
  • DATABASE_URL is set to sqlite+aiosqlite:///:memory: — a temporary in-memory SQLite database, no PostgreSQL instance needed.
  • REDIS_URL is set to redis://localhost:6379 — tests stub Redis calls via fixtures in conftest.py.
  • APP_ENV is set to test — disables Logfire tracing and other production-only middleware.
Tests use SQLite in-memory via conftest.py fixtures — no external database needed in CI. The test suite covers 86+ automated tests across API endpoints, services, and business logic, including farms CRUD, sensor readings, alert thresholds, KPI calculations, LLM service mocking, and email cooldown logic.

​
Deploy Job

The deploy-backend job only runs when all three conditions are true:
  1. The test job succeeded.
  2. The event is a push (not a pull_request).
  3. The branch is refs/heads/master.
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
The deploy steps are intentionally minimal — flyctl handles everything else:
  1. Check out the code (actions/checkout@v4).
  2. Install flyctl via superfly/flyctl-actions/setup-flyctl@master.
  3. Run flyctl deploy --remote-only from the backend/ directory.
The --remote-only flag builds the Docker image on Fly.io’s remote builders, so the GitHub-hosted runner never needs Docker installed locally.
The deploy job only runs on push to master — not on PRs. This means every pull request runs linting and tests to catch regressions, but only merged code reaches production.

​
Generating the Fly.io Deploy Token

The FLY_API_TOKEN secret authorises flyctl to deploy on behalf of your Fly.io account. 
# Generate a deploy token
flyctl auth token

# Copy the output, then add it to GitHub:
# Settings → Secrets and variables → Actions → New repository secret
# Name:  FLY_API_TOKEN
# Value: <token from above>

​
Frontend: Vercel GitHub Integration

The frontend deploy does not go through GitHub Actions. Vercel listens to the same GitHub repository via its native integration:
  • Pull requests → Vercel creates an isolated preview deployment with a unique URL.
  • Push to master → Vercel triggers an automatic production deploy to surqo.online.
No FLY_API_TOKEN equivalent is needed for the frontend — the Vercel connection is configured once in the Vercel dashboard and runs automatically thereafter. See the Frontend (Vercel) page for setup instructions.

​
Full Workflow Reference

The complete .github/workflows/ci-cd.yml defines three jobs: test, deploy-backend, and notify-deploy. The notify-deploy job runs after deploy-backend regardless of its result and prints a human-readable summary of what was deployed: 
Surqo deploy summary
  Backend  (Fly.io)  -> success
  Frontend (Vercel)  -> auto-deploy via GitHub integration
Deploy completo — surqo-api.fly.dev y surqo.online actualizados
If deploy-backend was skipped (because tests failed) or failed (because flyctl errored), notify-deploy exits with a non-zero code, making the overall workflow status red in the GitHub UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us