Skip to content

Team Use Setup

This guide walks you through setting up reviewGOOSE for your team. You'll create a configuration repository, install the GitHub App, configure Slack notifications, set up the web dashboard, and optionally add desktop notifications.

Time required: ~15 minutes

GitHub App Required

The reviewGOOSE Real-Time GitHub App is required for:

  • Real-time notifications (under 1 second)
  • Slack integration (server needs to know which repos to track)
  • Private repository access (Pro/Flock plans)

Install it on all organizations where you want PR tracking.

Step 1: Create Configuration Repository

reviewGOOSE uses a special .codeGROOVE repository in your GitHub organization to store configuration files.

  1. Go to your GitHub organization: https://github.com/your-org
  2. Click New repository
  3. Name it .codeGROOVE (note the leading dot)
  4. Choose Private (recommended) or Public
  5. Click Create repository

Why create this first?

Creating .codeGROOVE before installing the GitHub App ensures you can select it during installation. The app needs "Contents: Read" access to this repository to read your configuration files.

Step 2: Install GitHub App

Free for Public Repositories

Access to public repositories is completely free. Start with 1-2 public repos to evaluate, then expand later if needed.

  1. Visit: reviewGOOSE Real-Time GitHub App

  2. Click Install

  3. Choose your installation scope:

    • Select Only select repositories
    • Pick 1-2 public repositories for testing
    • Click Install

    Why public repos? They're lower risk for evaluation and let you verify the functionality before expanding to private repositories.

    • Select All repositories (or choose specific repos)
    • Click Install

Verify Installation

Visit your dashboard, login with GitHub, and confirm PRs appear within seconds.

Important: Include .codeGROOVE Repository

When selecting repositories during installation, you must include the .codeGROOVE repository. The app needs "Contents: Read" permission (already requested) to access .codeGROOVE/slack.yaml and other configuration files.

Step 3: View Dashboard

Visit your organization's dashboard at <your-org>.reviewgoose.dev (e.g., kubernetes.reviewgoose.dev), login with GitHub, and view your PRs organized by incoming (waiting on you) and outgoing (waiting on others).

The dashboard shows PRs from your organization and uses color-coded text badges like "ready to merge", "blocked on you", and "checks passing".

Step 4: Configure Slack

Install the Slack App

  1. Visit: Add to Slack

  2. Select your Slack workspace and click Allow

Privacy

The Slack app only accesses channels you explicitly invite it to.

Configure Slack Mapping

This step connects your Slack workspace to your GitHub organization.

Find Your Slack Team ID

You'll need this to validate that notifications go to the correct workspace.

  1. In Slack, click your workspace name in the top-left
  2. Select Settings & administration → Workspace settings
  3. Look at the URL in your browser address bar
  4. Your Team ID is in the URL (format: T09CJ7X7T7Y)
  5. Copy this ID
  1. Visit api.slack.com/methods/auth.test/test
  2. Click Test Method
  3. Copy the team_id from the response

Create Slack Configuration

In your .codeGROOVE repository, create slack.yaml:

global:
    team_id: T09CJ7X7T7Y        # Your Slack Team ID from step above
    email_domain: company.com   # Maps GitHub emails to Slack (alice@company.com → @alice)

channels:
    engineering:                 # Slack channel name (no # symbol)
        repos:
            - api-server         # GitHub repository name

Replace the team_id, email_domain, channel, and repo with your values.

global:
    team_id: T09CJ7X7T7Y
    email_domain: company.com

channels:
    engineering:
        repos:
            - api-server
            - mobile-app
    general:                    # Catch-all for unmapped repos
        repos:
            - "*"

Auto-discovery: Repos automatically map to same-named channels (e.g., backend repo → #backend channel). Only configure explicitly to override.

Commit and Push Configuration

  1. Add the file: git add slack.yaml
  2. Commit: git commit -m "Configure reviewGOOSE Slack integration"
  3. Push: git push

The app will automatically detect your configuration within 5 minutes.

Invite Bot to Channels

Now invite the bot to the Slack channels where you want PR notifications:

  1. Open the Slack channel (e.g., #engineering or #test-repo)
  2. Type and send: /invite @goose
  3. Repeat for each channel you want to receive notifications

Critical Step

The bot can only post to channels it's been invited to. Even with perfect configuration, you won't see messages until you invite the bot to the channel.

Evaluating?

Create a dedicated test channel like #goose-test to keep evaluation separate from your team's regular channels.

Verify Slack Integration

Create a test PR and confirm it appears in your Slack channel within seconds with status emoji updates.

Optional: Customize Notifications

Want to adjust notification timing? Add these settings to your slack.yaml:

global:
    team_id: T09CJ7X7T7Y
    email_domain: yourcompany.com
    reminder_dm_delay: 65  # Minutes to wait before DMing (default: 65)
    daily_reminders: true  # Send 8-9am reminders (default: false)

Smart DM logic:

  • If a reviewer is in the channel where they're tagged → Wait 65 minutes before sending DM
  • If a reviewer is NOT in that channel → Send DM immediately
  • Only one DM per user per PR, even if posted to multiple channels

See Slack Integration for complete configuration options.

Step 5: Desktop Integration (Optional)

What this enables: Native desktop notifications when PRs need your attention. Works on macOS, Windows, and Linux.

Security: Goose runs on your machine using your GitHub credentials. It communicates with GitHub's API and reviewGOOSE's Turn API for PR state analysis.

Installation Methods

Recommended method for macOS users:

# Install reviewGOOSE
brew install --cask codegroove-dev/tap/reviewgoose

# Authenticate with GitHub
gh auth status || gh auth login

Launch: Open /Applications/reviewGOOSE.app

Auto-start: Click menu bar icon → Start at Login

For Linux distributions with Homebrew (e.g., Bluefin):

# Install reviewGOOSE
brew install codegroove-dev/tap/reviewgoose

# Authenticate with GitHub
gh auth status || gh auth login

reviewGOOSE will be available in your applications menu.

For traditional Linux distributions:

# Install dependencies
# Debian/Ubuntu:
sudo apt install golang-go gh

# Fedora:
sudo dnf install golang gh

# Arch Linux:
sudo pacman -S go github-cli

# Authenticate with GitHub
gh auth login

# Install reviewGOOSE
go install github.com/codeGROOVE-dev/goose/cmd/reviewgoose@latest

Binary installed to ~/go/bin/reviewgoose. Add to auto-start for persistent notifications.

# Install dependencies (FreeBSD)
pkg install go gh git

# Authenticate with GitHub
gh auth login

# Install reviewGOOSE
go install github.com/codeGROOVE-dev/goose/cmd/reviewgoose@latest

Binary installed to ~/go/bin/reviewgoose.

Prerequisites: Install Go 1.23.4+ and GitHub CLI

# Authenticate with GitHub
gh auth login

# Install reviewGOOSE
go install github.com/codeGROOVE-dev/goose/cmd/reviewgoose@latest

Binary installed to %USERPROFILE%\go\bin\reviewgoose.exe. Add to startup for persistent notifications.

For developers or custom builds:

# Clone the repository
git clone https://github.com/codeGROOVE-dev/goose.git
cd goose

# Build and run
make run

macOS: Click menu bar icon → Start at Login for auto-launch.

Goose Credential Options

Default: Goose reuses credentials from your local gh tool (GitHub CLI).

For evaluation: Generate a GitHub Personal Access Token (PAT) with access to only public repositories:

  1. Create a token: github.com/settings/personal-access-tokens/new
  2. Grant permissions: Pull requests (Read), Metadata (Read)
  3. Select Public Repositories (read-only) for maximum security during evaluation
  4. Run: env GITHUB_TOKEN=your_token_here goose

This ensures Goose can only access public PRs during your evaluation period.

Verify It Works

Create a test PR in a repository where the GitHub App is installed. You should receive a desktop notification within seconds.

You're All Set! 🎉

Your team is now set up with reviewGOOSE. PRs will automatically appear in Slack channels with smart notifications to reviewers.

Next Steps

Explore Dashboard, Slack, Goose, or GitHub Bot documentation. For issues, see Troubleshooting or visit support.