# GitHub Integration Setup Guide

This guide covers all GitHub-related setup for the Quber project, including secrets management, project management, and potential Claude GitHub App integration.

## Quick Links
- [Secrets & API Keys Setup](#secrets--api-keys-setup)
- [Project Management Setup](#project-management-setup)
- [Claude GitHub App Setup](#claude-github-app-setup-optional)

## Prerequisites

- GitHub CLI (`gh`) installed and authenticated
- Repository admin access for secrets management
- GitHub Personal Access Token (for project management)

## Secrets & API Keys Setup

### Required Repository Secrets

The following secrets need to be added to GitHub for various integrations:

#### 1. Anthropic API Key (Required for Claude GitHub App)
```bash
# Add the secret using GitHub CLI
gh secret set ANTHROPIC_API_KEY --body "your-anthropic-api-key"

# Verify it was added
gh secret list
```

**Alternative via GitHub Web UI:**
1. Navigate to: https://github.com/xmandeng/quber/settings/secrets/actions
2. Click "New repository secret"
3. Name: `ANTHROPIC_API_KEY`
4. Value: Your API key from Anthropic Console
5. Click "Add secret"

### Environment Variables Reference

| Variable | Location | Purpose | Required For |
|----------|----------|---------|--------------|
| `ANTHROPIC_API_KEY` | `.env` (local) | Local development, CLI usage | Running quber locally |
| `ANTHROPIC_API_KEY` | GitHub Secrets | GitHub Actions, Claude App | Automated workflows |
| `GITHUB_PERSONAL_ACCESS_TOKEN` | `.env` (local) | The `github-workflow` agent's `gh` operations | Creating and reading PRs |
| `LOGFIRE_TOKEN` | `.env` (local) | Local logging/monitoring | Development debugging |

## Project Management

Work is tracked entirely in Jira, project key `QUE`. There is no GitHub Project
board, no GitHub Issues, and no labels carrying status. Create and update work
items through the `jira-workflow` agent; `docs/ISSUES_SPEC.md` defines the issue
types, templates, and evidence requirements.

GitHub carries the pull requests. `.github/workflows/jira-transition.yml` is the
only automation between the two, firing on branch creation and on a PR opening
or closing. `docs/GITHUB_WORKFLOW_SPEC.md` defines branch naming, PR format, and
what evidence a PR must show.

## Claude GitHub App Setup (Optional)

### What It Provides
- AI-powered code implementation
- Responds to `@claude` mentions in issues/PRs
- Automatic PR creation with code changes
- Respects project conventions in `CLAUDE.md`

### Installation Steps

#### Method 1: Using Claude Code CLI (Recommended)
```bash
# In Claude Code terminal
/install-github-app
```
This will guide you through:
1. Installing the GitHub App to your repository
2. Configuring the `ANTHROPIC_API_KEY` secret (already done above)
3. Adding the workflow file

#### Method 2: Manual Setup

1. **Install GitHub App**
   - Visit: https://github.com/apps/claude-code
   - Click "Install"
   - Select your repository

2. **Add Workflow File**
   Create `.github/workflows/claude.yml`:
   ```yaml
   name: Claude Code

   on:
     issues:
       types: [opened, edited]
     issue_comment:
       types: [created, edited]
     pull_request:
       types: [opened, edited, synchronize]
     pull_request_review_comment:
       types: [created, edited]

   jobs:
     claude:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: anthropics/claude-code@v1
           with:
             anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
   ```

### Using Claude GitHub App

Once installed, you can:
```markdown
# In any issue or PR comment:
@claude implement this feature following our conventions

# Claude will:
1. Read the issue context
2. Check CLAUDE.md for project guidelines
3. Create a PR with implementation
4. Link it back to the issue
```

## Verification Checklist

- [ ] GitHub CLI (`gh`) is authenticated: `gh auth status`
- [ ] Repository secrets are set: `gh secret list`
- [ ] CLAUDE.md exists with project conventions
- [ ] (Optional) Claude GitHub App is installed
- [ ] (Optional) `.github/workflows/claude.yml` exists

## Troubleshooting

### Common Issues

1. **"Permission denied" when setting secrets**
   - Ensure you have admin access to the repository
   - Check: `gh api repos/xmandeng/quber --jq '.permissions.admin'`

2. **Jira not transitioning on a PR**
   - Check the run: `gh run list --workflow="jira-transition.yml" --limit 5`
   - Confirm the branch name carries a valid `QUE-XXX` key

3. **Claude not responding to mentions**
   - Verify `ANTHROPIC_API_KEY` is set in secrets
   - Check workflow file exists and is valid
   - Ensure Claude GitHub App is installed on the repository

4. **Local commands failing**
   - Verify `.env` file has required keys
   - Run: `source .env` to load environment variables

## Security Notes

- **Never commit** `.env` files to version control
- **Rotate keys regularly** if they may have been exposed
- **Use fine-grained tokens** with minimal required permissions
- **Repository secrets** are encrypted and only visible to actions
- **Audit log** available in Settings → Security → Audit log

## Next Steps

1. Confirm `gh auth status` and `gh secret list` both succeed
2. Open a branch named `<type>/QUE-XXX-description` and check that
   `jira-transition.yml` runs
3. (Optional) Test Claude integration with a simple `@claude` mention