Getting Started

Repo Relay runs as a GitHub Action. The fastest path is the interactive init wizard; a manual path is also documented for full control. Full details live in the repo-relay README.

Fastest path: the init wizard

npx blamechris/repo-relay init

The wizard guides you through setup and creates the workflow file automatically. After it finishes, add the Discord secrets described in Configuration and you are done.

Manual setup

1. Create the Discord bot

Open the Discord Developer Portal.
Create a new application, add a Bot, reset the token, and copy it.
Enable the Message Content Intent and Server Members Intent.
Generate an invite URL (OAuth2 → URL Generator) with the bot scope and the permissions listed in Required Discord Permissions.
Invite the bot to your server.

2. Get channel IDs

Enable Developer Mode in Discord (Settings → Advanced → Developer Mode), then right-click each target channel and choose Copy ID.

3. Add secrets to the repository

Add the secrets under Settings → Secrets and variables → Actions. The PR channel and bot token are required; the rest are optional and fall back to the PR channel. See Configuration for the full table.

4. Add the workflow

Create .github/workflows/discord-notify.yml:

name: Discord Notifications
 
on:
  pull_request:
    types: [opened, synchronize, closed, reopened, edited, ready_for_review, converted_to_draft]
  pull_request_review:
    types: [submitted]
  issue_comment:
    types: [created]
  issues:
    types: [opened, closed]
  release:
    types: [published]
  workflow_run:
    workflows: ["CI"]  # Name of your CI workflow
    types: [completed]
 
jobs:
  notify:
    runs-on: self-hosted  # or ubuntu-latest — see Runners
    permissions:
      pull-requests: read
      issues: read
      contents: read
    if: github.event_name != 'workflow_run' || github.event.workflow_run.pull_requests[0] != null
 
    steps:
      - uses: blamechris/repo-relay@v1
        with:
          discord_bot_token: ${{ secrets.DISCORD_BOT_TOKEN }}
          channel_prs: ${{ secrets.DISCORD_CHANNEL_PRS }}
          channel_issues: ${{ secrets.DISCORD_CHANNEL_ISSUES }}
          channel_releases: ${{ secrets.DISCORD_CHANNEL_RELEASES }}

The composite action handles Node.js setup, dependency installation, and execution.

First run

The first PR will fail before secrets are configured (it shows a red X). This is expected — configure the secrets, then re-run the failed workflow. Future PRs work normally. See Troubleshooting if the bot connects but cannot post.

Next steps

Tune channels, inputs, and permissions in Configuration.
Decide where the job runs and how state is kept in Runners and State Persistence.
Understand what each event produces in the Event and Notification Model.

Repo Relay Documentation

Explorer