Skip to content

Commit 49af881

Browse files
prognostikosprognostikos
authored
Add Claude Code GitHub Workflow (#21)
* "Claude PR Assistant workflow" * "Claude Code Review workflow" * only review on workflow dispatch * Add CLAUDE.md [ci skip]
1 parent 96c2eb1 commit 49af881

3 files changed

Lines changed: 219 additions & 0 deletions

File tree

‎.github/workflows/claude-code-review.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Claude Code Review
2+
3+
on:
4+
workflow_dispatch:
5+
# pull_request:
6+
# types: [opened, synchronize]
7+
# # Optional: Only run on specific file changes
8+
# # paths:
9+
# # - "src/**/*.ts"
10+
# # - "src/**/*.tsx"
11+
# # - "src/**/*.js"
12+
# # - "src/**/*.jsx"
13+
14+
jobs:
15+
claude-review:
16+
# Optional: Filter by PR author
17+
# if: |
18+
# github.event.pull_request.user.login == 'external-contributor' ||
19+
# github.event.pull_request.user.login == 'new-developer' ||
20+
# github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
21+
22+
runs-on: ubuntu-latest
23+
permissions:
24+
contents: read
25+
pull-requests: read
26+
issues: read
27+
id-token: write
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
with:
33+
fetch-depth: 1
34+
35+
- name: Run Claude Code Review
36+
id: claude-review
37+
uses: anthropics/claude-code-action@v1
38+
with:
39+
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
40+
prompt: |
41+
REPO: ${{ github.repository }}
42+
PR NUMBER: ${{ github.event.pull_request.number }}
43+
44+
Please review this pull request and provide feedback on:
45+
- Code quality and best practices
46+
- Potential bugs or issues
47+
- Performance considerations
48+
- Security concerns
49+
- Test coverage
50+
51+
Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
52+
53+
Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
54+
55+
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
56+
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
57+
claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
58+

‎.github/workflows/claude.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Claude Code
2+
3+
on:
4+
issue_comment:
5+
types: [created]
6+
pull_request_review_comment:
7+
types: [created]
8+
issues:
9+
types: [opened, assigned]
10+
pull_request_review:
11+
types: [submitted]
12+
13+
jobs:
14+
claude:
15+
if: |
16+
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
17+
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
18+
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
19+
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
20+
runs-on: ubuntu-latest
21+
permissions:
22+
contents: read
23+
pull-requests: read
24+
issues: read
25+
id-token: write
26+
actions: read # Required for Claude to read CI results on PRs
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 1
32+
33+
- name: Run Claude Code
34+
id: claude
35+
uses: anthropics/claude-code-action@v1
36+
with:
37+
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
38+
39+
# This is an optional setting that allows Claude to read CI results on PRs
40+
additional_permissions: |
41+
actions: read
42+
43+
# Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
44+
# prompt: 'Update the pull request description to include a summary of changes.'
45+
46+
# Optional: Add claude_args to customize behavior and configuration
47+
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
48+
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
49+
# claude_args: '--allowed-tools Bash(gh pr:*)'
50+

‎CLAUDE.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the BetterNow API Developer Documentation site (`developers.betternow.org`), a static documentation site that uses **schema-driven documentation generation**. API documentation is automatically generated from YAML schema definitions using PRMD, then combined with custom content and built into a static site using Middleman.
8+
9+
## Development Commands
10+
11+
### Local Development
12+
```bash
13+
# Start local development server with live reload
14+
docker compose up
15+
16+
# Access at http://localhost:4567 or http://bndocs.test (if puma-dev configured)
17+
18+
# Build inside running container
19+
docker compose exec web bin/build
20+
```
21+
22+
### Build Process
23+
```bash
24+
# Full build (schema compilation → docs generation → static site)
25+
bin/build
26+
27+
# Or step by step:
28+
bundle exec rake schema:combine # Combine YAML schemas → source/schema.json
29+
bundle exec rake schema:verify # Validate compiled schema
30+
bundle exec rake schema:doc # Generate source/includes/resources.md
31+
bundle exec middleman build # Build static site → build/
32+
```
33+
34+
### Rake Tasks
35+
```bash
36+
rake # Default: combine, verify, doc
37+
rake schema:combine # Combine schema YAML files into source/schema.json
38+
rake schema:verify # Validate the compiled schema
39+
rake schema:doc # Generate Markdown docs from schema
40+
```
41+
42+
### Deployment
43+
- Automatic deployment via GitHub Actions on push to master branch
44+
- Deploys to AWS S3 using OIDC authentication (no hardcoded credentials)
45+
- Manual deploy: `bin/deploy` (requires AWS credentials)
46+
47+
## Architecture
48+
49+
### Schema-Driven Documentation Flow
50+
```
51+
schema/schemata/*.yml → [rake schema:combine] → source/schema.json
52+
↓
53+
[rake schema:doc]
54+
↓
55+
source/index.html.md + source/includes/resources.md → [middleman build] → build/
56+
```
57+
58+
### Key Directories
59+
60+
- **`schema/schemata/`** - YAML schema definitions for each API resource (16 total resources)
61+
- `common.yml` - Shared field definitions referenced by other schemas
62+
- Individual resource schemas: `fundraiser.yml`, `donation.yml`, `person.yml`, etc.
63+
- **`schema/meta.json`** - Schema metadata (API title, URL, description)
64+
- **`schema/preface.md`** - Content prepended to generated API docs
65+
- **`source/index.html.md`** - Main landing page (YAML frontmatter + Markdown)
66+
- **`source/includes/`** - Markdown sections included in final docs
67+
- `resources.md` - Generated API reference (DO NOT EDIT DIRECTLY)
68+
- `webhooks.md` - Webhook documentation (manually maintained)
69+
- **`source/schema.json`** - Compiled schema (generated, DO NOT EDIT)
70+
71+
### Important Build Patterns
72+
73+
1. **Generated Files** - These are auto-generated and should NOT be edited directly:
74+
- `source/schema.json` (from `rake schema:combine`)
75+
- `source/includes/resources.md` (from `rake schema:doc`)
76+
77+
2. **To Modify API Documentation**:
78+
- Edit YAML files in `schema/schemata/`
79+
- Run `bin/build` to regenerate docs
80+
- The build process validates schemas automatically
81+
82+
3. **To Modify Landing Page or Static Content**:
83+
- Edit `source/index.html.md` for main page
84+
- Edit `source/includes/webhooks.md` for webhook docs
85+
- Run `middleman build` or full `bin/build`
86+
87+
4. **Schema References**:
88+
- Common fields defined in `schema/schemata/common.yml` are referenced via `$ref`
89+
- PRMD automatically resolves these references during `schema:combine`
90+
91+
## Technology Stack
92+
93+
- **Ruby 2.7.6** - Runtime (managed via Docker)
94+
- **Middleman** - Static site generator
95+
- **PRMD v0.12.0** - JSON Schema to Markdown converter for API docs
96+
- **Redcarpet** - Markdown processor with table/code block support
97+
- **Rouge** - Syntax highlighting (via `middleman-syntax`)
98+
- **Docker/Docker Compose** - Local development environment
99+
100+
## API Specifications
101+
102+
- **Base URL**: `https://api.betternow.org`
103+
- **HTTP Header**: `Accept: application/vnd.betternow+json; version=1`
104+
- **Authentication**: Publishable (read-only) and Secret (write) API keys
105+
106+
## CI/CD
107+
108+
GitHub Actions workflow (`.github/workflows/publish.yml`) automatically:
109+
1. Builds the site on push to master
110+
2. Deploys to AWS S3 bucket
111+
3. Uses AWS OIDC for secure authentication

0 commit comments

Comments
 (0)