Skip to content

serverlessship.md

Latest commit

 

History

History
94 lines (66 loc) · 3.36 KB

serverlessship.md

File metadata and controls

94 lines (66 loc) · 3.36 KB
Raw

ServerlessShip

Serverless Feishu deploy notifier for minibot

ServerlessShip is the lightweight serverless companion service for minibot deployments. It is designed for a Vercel Hobby + Supabase Free stack and turns GitHub release or deploy events into Feishu notifications.

One-line goal

When a minibot deployment finishes, ServerlessShip should send a polished Feishu notification to the right people without requiring a long-running backend.

Why this name

  • Serverless: the service is intended to run as Vercel serverless functions
  • Ship: it focuses on shipping minibot releases
  • Feishu: notifications are delivered to Feishu users or groups

Intended stack

  • Vercel Hobby for the API layer and scheduled jobs
  • Supabase Free for persistence and lightweight state
  • GitHub Actions for release or deployment triggers
  • Feishu app or bot messaging for delivery

MVP architecture

flowchart LR
  A["GitHub Actions / manual release"] --> B["Vercel API route"]
  B --> C["Supabase tables"]
  B --> D["Feishu OpenAPI"]
  D --> E["Feishu user or group"]
  B --> F["Delivery log / retry state"]
Loading

Responsibilities

  • GitHub Actions: emits deployment completed events or calls a webhook after publish-desktop
  • Vercel serverless: receives the event, formats the message, and calls Feishu
  • Supabase: stores recipients, notification targets, release history, and delivery logs
  • Feishu: delivers either a direct user message or a group message depending on the configured channel

Core job

  • Receive deployment completion events
  • Format a release notification card
  • Send the message to the target Feishu recipient
  • Record delivery state for retries and audit

API entry points

  • GET /api/health for uptime checks
  • POST /api/releases for direct GitHub Actions or release pipeline calls
  • POST /api/webhooks/github for GitHub release and workflow-run webhooks

Deployment workflow

  • Pushes to main can deploy to Vercel through the included GitHub Actions workflow
  • The workflow uses VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID
  • The custom domain serverless-ship.liuyidi.me is mapped to the project and should serve the production deployment

Feishu app message mode

  • Set FEISHU_APP_ID and FEISHU_APP_SECRET to enable app identity delivery
  • Set FEISHU_TARGET_OPEN_ID for direct user delivery
  • Optionally set FEISHU_TARGET_ID_TYPE to open_id
  • If FEISHU_WEBHOOK_URL is also present, webhook delivery still works as a fallback path

Suggested MVP data

  • projects: one row per business or deployment target
  • releases: version, tag, release URL, workflow URL, status
  • deliveries: one row per notification attempt

The current implementation uses the first three tables only. RLS is enabled on those tables and access stays server-side through the Supabase service role. targets and Feishu token persistence can be added later if the service needs user- or group-specific routing state in Supabase.

What this intentionally does not do

  • It does not run the actual build
  • It does not replace GitHub Releases
  • It does not try to become a general chat platform
  • It does not keep a persistent worker process alive

Good fit

This setup is a good fit if the first version only needs:

  • one or a few deploy pipelines
  • Feishu notification delivery
  • simple retry and audit history
  • low ops overhead