Repo Relay Documentation

Developer Guide

3 min read

This page covers the source layout, build commands, and how to extend Repo Relay. The authoritative source is the repo-relay repository.

Tech stack

  • Node.js 20+
  • TypeScript targeting ES2022
  • discord.js 14.x
  • better-sqlite3 for state
  • License: MIT

Project layout

src/
  cli.ts            CLI entry point for GitHub Actions; maps the GitHub event name
  index.ts          RepoRelay class, Discord connect/permissions, event routing
  pre-filter.ts     Skips events handlers would discard (saves a gateway session)
  config/
    channels.ts     Channel configuration and per-event routing
  db/
    state.ts        SQLite state (StateDb class)
  embeds/
    builders.ts     Discord embed builders (PR, issue, release, ...)
  github/
    reviews.ts      Piggyback review detection helpers
    ci.ts           CI / workflow-run helpers
  handlers/
    index.ts        Handler exports
    pr.ts           Pull request events; embed building
    ci.ts           Workflow run events
    review.ts       PR review events
    comment.ts      Issue comment events (including agent-review detection)
    issue.ts        Issue events
    release.ts      Release events
    deployment.ts   Deployment status events
    push.ts         Push events
    security.ts     Dependabot / secret scanning / code scanning alerts
  patterns/
    agent-review.ts Shared agent-review detection patterns
  commands/         Discord slash commands (secondary)
  setup/            Workflow-template generation for the init wizard

Development commands

npm install       # Install dependencies
npm run build     # Compile TypeScript to dist/
npm run dev       # Run with tsx for local testing
npm run typecheck # Type check without emitting
npm run lint      # Run ESLint

Local runs read the same environment variables the action sets.

How an event flows through the code

The CLI reads the GitHub event, mapGitHubEvent() turns the event name into a typed internal event, the pre-filter drops no-op events, and RepoRelay.handleEvent() dispatches to the matching handler. Handlers read and write the state DB and create or edit Discord messages. After PR and CI events, the piggyback review check runs if a GitHub token is available. See Architecture for the runtime picture.

Adding a new handler

  1. Create src/handlers/{event}.ts with the handler function.
  2. Export it from src/handlers/index.ts.
  3. Add a case to handleEvent() in src/index.ts.
  4. Add the event mapping in mapGitHubEvent() in src/cli.ts.
  5. Route the event to a channel in config/channels.ts if it needs its own channel.

Common patterns

  • Rebuilding an embed: use buildEmbedWithStatus() to pull current DB status, then buildPrEmbed(...) and edit the message in place.
  • Thread operations: use getOrCreateThread() to safely fetch or create a PR thread; it also recovers from archived or deleted threads.
  • Stale messages: handlers catch the “Unknown Message” error, clear the DB entry, and recreate the embed and thread.

Packaging as an action

Repo Relay ships as a composite GitHub Action (action.yml). The action sets up Node 20, installs production dependencies, validates inputs, and runs node dist/cli.js. Consumers reference blamechris/repo-relay@v1, which resolves to the v1 tag; the tag is moved forward when changes ship.

Graph View

Backlinks