Rehearsal QA Bot

AI-powered GitHub Action that enables Claude to interact with PRs and issues for automated testing and code review. Responds to mentions, executes QA workflows, and manages test branches.

How It Works

This action operates in two phases:

Phase 1: Preparation

1. Authenticate with GitHub (OIDC or GitHub App)

2. Validate permissions and detect trigger conditions

3. Prepare GitHub context and create tracking comment

Phase 2: Execution

1. Set up MCP servers for GitHub tool access

2. Generate context-rich prompts from PR/issue data

3. Execute via Claude API (Anthropic, AWS Bedrock, or Google Vertex AI)

4. Update comments and create branches/PRs with results

Execution Modes

Tag Mode

Agent Mode

Step-by-Step Instructions

When working with this codebase:

1. **Understand the Architecture**

- Review `src/entrypoints/prepare.ts` for preparation logic

- Examine `base-action/` for core Claude Code execution

- Study mode implementations in `src/modes/`

2. **Authentication & Security**

- Use OIDC token exchange (secure, recommended)

- Or configure GitHub App with `APP_ID` + `APP_PRIVATE_KEY`

- Validate actor permissions via `src/github/validation/permissions.ts`

3. **MCP Server Integration**

- Servers auto-install in `~/.claude/mcp/github-{type}-server/`

- Three server types: actions, comments, file-ops

- Configuration merges with user `mcp_config` input

4. **GitHub Data Fetching**

- Use `src/github/data/fetcher.ts` for PR/issue data

- Format with `src/github/data/formatter.ts` for Claude consumption

- Handle images via `src/github/utils/images/download-images.ts`

5. **Comment Management**

- Create tracking comments early in preparation phase

- Update with progress checkboxes during execution

- Use sticky comments for consolidated PR feedback

6. **Branch Operations**

- Create test branches via `src/github/operations/branch.ts`

- Follow naming convention: `claude/{mode}/{timestamp}`

- Clean up branches after testing completes

7. **Testing & Development**

- Run tests: `bun test`

- Type check: `bun run typecheck`

- Format code: `bun run format`

8. **Common Pitfalls**

- Agent mode ONLY works with workflow_dispatch/schedule events

- Validate actor is human (not bot) for tag mode

- Handle GitHub API rate limits with retry logic (`utils/retry.ts`)

- Sanitize markdown content before posting comments

9. **Extending Modes**

- Implement `Mode` interface with `shouldTrigger()` and `prepare()`

- Register in `src/modes/registry.ts`

- Ensure mode compatibility with GitHub event types

10. **Error Handling**

- Use explicit error messages for debugging

- Implement retry logic for transient GitHub API failures

- Update tracking comments with error status

Key Files

Configuration

Set up via GitHub Actions workflow inputs:

Constraints

Example Usage

**Tag mode (PR comment):**

```

@claude please review this PR and run integration tests

```

**Agent mode (workflow_dispatch):**

```yaml

on:

workflow_dispatch:

inputs:

task:

description: 'Task for Claude'

required: true

jobs:

qa:

runs-on: ubuntu-latest

steps:

- uses: anthropics/rehearsal-claude-action@v1

with:

mode: agent

anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

custom_instructions: ${{ inputs.task }}

```