Skip to content

Commit ef691ec

Browse files
cmungallcmungall
authored
Merge pull request #64 from dragon-ai-agent/docs/issue-15-claude-github-integrations
Add GitHub AI integrations comparison documentation
2 parents 81da449 + da49a3f commit ef691ec

2 files changed

Lines changed: 165 additions & 0 deletions

File tree

‎docs/reference/github-integrations.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# GitHub AI Integrations
2+
3+
This guide documents the different approaches for integrating AI agents with GitHub workflows in ontology repositories. Each approach has different trade-offs in terms of setup complexity, billing, and capabilities.
4+
5+
## Overview
6+
7+
| Approach | Billing | Model Selection | Setup Complexity | Best For |
8+
|----------|---------|-----------------|------------------|----------|
9+
| [Dragon-AI Agent](#dragon-ai-agent) | API key (project-based) | Configurable | Medium | Custom workflows, team control |
10+
| [GitHub Copilot](#github-copilot) | GitHub subscription | GitHub-controlled | Low | Quick setup, GitHub-native |
11+
| [Claude Code Action](#claude-code-action) | API key or Max subscription | Anthropic models | Low-Medium | Claude-specific features |
12+
13+
## Dragon-AI Agent
14+
15+
The Dragon-AI Agent approach uses custom GitHub Actions to deploy headless AI coding assistants (Claude Code or Goose) in response to issue/PR comments.
16+
17+
### How It Works
18+
19+
1. A controller invokes the agent with `@dragon-ai-agent please` in an issue or PR comment
20+
2. A GitHub Action triggers, running the AI in a containerized environment
21+
3. The AI reads the issue context, makes changes, and creates/updates PRs
22+
4. Controllers are authorized via `.github/ai-controllers.json`
23+
24+
### Setup
25+
26+
See [Set up GitHub Actions](../how-tos/set-up-github-actions.md) for detailed setup instructions.
27+
28+
Key configuration files:
29+
- `.github/workflows/` - GitHub Action workflow definitions
30+
- `.github/ai-controllers.json` - Authorized users list
31+
- `CLAUDE.md` - AI system instructions
32+
33+
### When to Use
34+
35+
- **Team control**: You want fine-grained control over who can invoke the AI
36+
- **Custom tooling**: Your workflow requires specific MCP servers or tools
37+
- **Project billing**: You want to charge AI usage to a specific project/grant via API proxy
38+
- **Multi-model support**: You need to switch between different AI providers
39+
40+
### Limitations
41+
42+
- Requires maintenance of GitHub Action workflows
43+
- Setup is more involved than native integrations
44+
- Debugging requires checking GitHub Actions logs
45+
46+
## GitHub Copilot
47+
48+
GitHub Copilot's coding agent can be assigned to issues and PRs directly through the GitHub interface.
49+
50+
### How It Works
51+
52+
1. Assign an issue to Copilot - it creates a PR to address the issue
53+
2. Assign a PR to Copilot - it reviews and suggests changes
54+
3. Copilot works within GitHub's infrastructure
55+
56+
### Setup
57+
58+
1. Enable GitHub Copilot for your organization/repository
59+
2. Copilot appears as an assignable user on issues and PRs
60+
61+
For educational users, see the [GitHub Education benefits](../how-tos/instruct-github-agent.md#github-copilot-pro-coupon-through-github-education) section for free Copilot Pro access.
62+
63+
### When to Use
64+
65+
- **Quick setup**: You want to start using AI agents immediately
66+
- **GitHub-native**: You prefer staying within GitHub's ecosystem
67+
- **Individual use**: For personal repositories or small teams
68+
- **PR reviews**: Copilot excels at code review tasks
69+
70+
### Limitations
71+
72+
- Less control over model selection and behavior
73+
- Billing tied to GitHub subscription
74+
- May not support ontology-specific tooling (ROBOT, OWL tools)
75+
- Configuration options are limited compared to custom approaches
76+
77+
### Ontology-Specific Considerations
78+
79+
For ontology repositories, Copilot may need additional guidance:
80+
81+
- Include clear instructions in repository documentation
82+
- Copilot may attempt to run tools locally before using ODK wrappers
83+
- Add prominent warnings in README/CLAUDE.md about using ODK containers
84+
85+
## Claude Code Action
86+
87+
Anthropic's official [Claude Code Action](https://github.com/anthropics/claude-code-action) provides a streamlined way to run Claude Code in GitHub Actions.
88+
89+
### How It Works
90+
91+
1. Trigger via issue/PR comments (configurable trigger phrase)
92+
2. Claude Code runs with access to repository contents
93+
3. Can create commits, PRs, and respond to comments
94+
95+
### Setup
96+
97+
Install via Claude Code:
98+
```bash
99+
claude /install-github-app
100+
```
101+
102+
Or manually add the GitHub Action to your repository.
103+
104+
**Billing options:**
105+
- API key (pay-per-use via Anthropic API)
106+
- Claude Max subscription (included usage)
107+
108+
### When to Use
109+
110+
- **Claude-specific features**: You want access to latest Claude capabilities
111+
- **Simple setup**: Official action with maintained support
112+
- **Flexible billing**: Choose between API or subscription billing
113+
- **Anthropic ecosystem**: Already using Claude for other workflows
114+
115+
### Limitations
116+
117+
- Limited to Anthropic models
118+
- Less customization than Dragon-AI approach
119+
- Requires Anthropic API key or Max subscription
120+
121+
## Comparison for Ontology Repositories
122+
123+
For ontology curation workflows, consider these factors:
124+
125+
### Tool Access
126+
127+
| Tool | Dragon-AI | Copilot | Claude Code Action |
128+
|------|-----------|---------|-------------------|
129+
| ROBOT via ODK | Yes (configurable) | Limited | Yes (configurable) |
130+
| OWL-MCP | Yes | No | Yes |
131+
| Custom MCP servers | Yes | No | Yes |
132+
| Web search | Yes | Limited | Yes |
133+
134+
### Recommended Approach by Use Case
135+
136+
**Starting out / Experimentation:**
137+
- Use GitHub Copilot for quick wins on simple issues
138+
- Low barrier to entry, good for learning
139+
140+
**Production ontology curation:**
141+
- Use Dragon-AI Agent or Claude Code Action
142+
- Better tool integration and customization
143+
- Project-based billing for grant compliance
144+
145+
**Mixed team (technical + non-technical):**
146+
- Dragon-AI Agent with clear controller authorization
147+
- Provides guardrails while enabling AI assistance
148+
149+
## Configuration Files
150+
151+
Regardless of which approach you use, these files help guide AI behavior:
152+
153+
| File | Purpose |
154+
|------|---------|
155+
| `CLAUDE.md` | System instructions for Claude-based agents |
156+
| `.goosehints` | Instructions for Goose (often symlinked to CLAUDE.md) |
157+
| `.github/copilot-instructions.md` | Instructions for GitHub Copilot |
158+
| `.github/ai-controllers.json` | Authorized users for Dragon-AI |
159+
160+
## Related Resources
161+
162+
- [Set up GitHub Actions](../how-tos/set-up-github-actions.md)
163+
- [Instruct the GitHub Agent](../how-tos/instruct-github-agent.md)
164+
- [Claude Code Action Repository](https://github.com/anthropics/claude-code-action)

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ nav:
4848
- Ontology editing with AI: tutorials/ontology-editing-with-ai.md
4949
- Reference:
5050
- Client apps: reference/client-apps.md
51+
- GitHub integrations: reference/github-integrations.md
5152
- Claude Skills: reference/claude-skills.md
5253
- Clients:
5354
- Claude Desktop: reference/clients/claude-desktop.md

0 commit comments

Comments
 (0)