# GitHub Actions CI/CD Workflows

This directory contains automated workflows for code quality, testing, and AI-powered code reviews.

## Workflows

### 1. Python Code Quality (`python-quality.yml`)

**Triggers:**
- Push to `main` (when Python files change)
- Pull requests to `main` (when Python files change)

**What it does:**
- Runs on Python 3.11 and 3.12
- **Linting**: `ruff check` for code quality
- **Formatting**: `ruff format --check` for style consistency
- **Type checking**: `mypy` for type safety
- **Testing**: `pytest` with coverage reporting
- **Coverage**: Uploads to Codecov (optional)

**Path filters:**
- `**/*.py` - Any Python file changes
- `.github/workflows/python-quality.yml`
- `pyproject.toml`
- `requirements*.txt`

### 2. Claude PR Review (`claude-pr-review.yml`)

**Triggers:**
- Pull request opened or updated (synchronized)

**What it does:**
- Automatically reviews PRs using Claude Code
- Checks code quality against engineering standards
- Reviews Python best practices, security, and test coverage
- Posts review feedback as PR comment

**Requirements:**
- `CLAUDE_CODE_OAUTH_TOKEN` secret configured
- Only runs on internal PRs (not forks)

**Permissions:**
- `contents: read` - Read repository code
- `pull-requests: write` - Post review comments
- `issues: read` - Read issue context
- `id-token: write` - OIDC authentication

### 3. Claude on @mention (`claude-on-mention.yml`)

**Triggers:**
- Issue comment created
- PR review comment created
- Issue opened or assigned
- PR review submitted

**What it does:**
- Responds when `@claude` is mentioned in:
  - Issue comments
  - PR comments
  - PR reviews
  - Issue titles/descriptions
- Executes the instruction specified in the mention
- Can read CI results and provide context-aware responses

**Requirements:**
- `CLAUDE_CODE_OAUTH_TOKEN` secret configured

**Example usage:**
```
@claude please review the error handling in this function
@claude add unit tests for the new feature
@claude explain how this workflow works
```

### 4. ShellCheck (`shellcheck.yml`)

**Triggers:**
- Push to `main` (when shell scripts change)
- Pull requests to `main` (when shell scripts change)

**What it does:**
- Lints all bash scripts in `.claude/` and `.claude/git-hooks/`
- Enforces **zero global disables policy** (only inline disables allowed)
- Verifies hook scripts are executable
- Catches common shell scripting errors and security issues

**Path filters:**
- `.claude/**/*.sh`
- `.claude/git-hooks/**`
- `.github/workflows/shellcheck.yml`

**Policy:**
- Global `# shellcheck disable=` at file level is **FORBIDDEN**
- Fix the code, not the linter
- If necessary, use inline disables for specific lines only

### 5. Copilot PR Reviews

**Note:** GitHub Copilot PR reviews are **not** configured via workflow files.

**How to enable:**

1. Go to repository **Settings** → **Code security and analysis**
2. Under **Copilot**, enable **Copilot Autofix**
3. Enable **Copilot pull request summaries**
4. Copilot will automatically review PRs when opened or updated

**What Copilot reviews:**
- Code quality and best practices
- Potential bugs
- Security vulnerabilities
- Performance issues

## Setup Instructions

### Required Secrets

Add these secrets to your repository (Settings → Secrets and variables → Actions):

1. **ANTHROPIC_API_KEY**
   - Generate at: https://console.anthropic.com/settings/keys
   - Create a new API key for GitHub Actions
   - Add as organization or repository secret
   - **Important**: Ensure your Anthropic account has sufficient credits
   - Check balance at: https://console.anthropic.com/settings/billing
   - Workflow will fail with "Credit balance is too low" if credits are insufficient

### Optional Secrets

1. **CODECOV_TOKEN** (for coverage reporting)
   - Sign up at: https://codecov.io/
   - Add your repository
   - Copy the token and add as secret

### Authentication Notes

The Claude PR Review workflow uses direct API key authentication (`anthropic_api_key`) instead of OAuth tokens. This allows the workflow to:
- ✅ Review PRs opened by users with write access
- ✅ Review PRs opened by GitHub App bots (e.g., Copilot)
- ✅ Work without OIDC permission validation

**Previous setup (deprecated):**
- `CLAUDE_CODE_OAUTH_TOKEN` - Required OIDC with write access, failed for bot PRs

## Testing Workflows Locally

### Python Quality Checks

Run the same checks locally before pushing:

```bash
# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Run linting
ruff check .

# Check formatting
ruff format --check .

# Type check (adjust path to your source directory)
mypy src/

# Run tests
pytest tests/ -v
```

Or use `just check` to run all quality checks at once.

### ShellCheck

Run ShellCheck on bash scripts:

```bash
# Install ShellCheck
# macOS: brew install shellcheck
# Ubuntu: sudo apt install shellcheck

# Check all scripts
find .claude -name "*.sh" -exec shellcheck {} \;

# Check git hooks (no .sh extension)
shellcheck .claude/git-hooks/pre-push
```

### Test Workflow Syntax

```bash
# Validate workflow YAML syntax
gh workflow list
gh workflow view python-quality.yml
```

## Workflow Status

Check workflow status:
- Visit: https://github.com/{owner}/{repo}/actions
- Or use CLI: `gh run list`

## Troubleshooting

### Claude workflows not running

**Check:**
1. `CLAUDE_CODE_OAUTH_TOKEN` secret is configured
2. PR is from the same repository (not a fork)
3. Workflow file syntax is valid

### Python quality checks failing

**Common issues:**
1. **Linting errors**: Run `ruff check --fix` to auto-fix
2. **Type errors**: Add missing type hints, fix Optional usage
3. **Test failures**: Check test output and fix failing tests

### ShellCheck failing

**Common issues:**
1. **SC2086 (word splitting)**: Quote variables: `"$var"` instead of `$var`
2. **SC2164 (cd failure)**: Use `cd dir || exit` to handle failures
3. **Global disable found**: Move disable to inline (specific line only)
4. **Fix the code**: Don't globally disable warnings - fix the underlying issue

### Copilot not reviewing

**Check:**
1. Copilot is enabled in repository settings
2. You have a GitHub Copilot subscription
3. Repository has Copilot access permissions

## Best Practices

1. **Keep workflows fast**: Use path filters to only run when relevant files change
2. **Test locally first**: Run quality checks before pushing
3. **Review AI feedback**: Claude and Copilot provide suggestions, not requirements
4. **Iterate on feedback**: Use `/iterate-pr` to automatically address review comments

## Further Reading

- [Claude Code Action Documentation](https://github.com/anthropics/claude-code-action)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [GitHub Copilot Documentation](https://docs.github.com/en/copilot)
- [Ruff Documentation](https://docs.astral.sh/ruff/)
- [mypy Documentation](https://mypy.readthedocs.io/)
- [ShellCheck Documentation](https://www.shellcheck.net/) - Shell script linter
