Vlad MocanuandClaude Opus 4.6
44f598ff11
- Created docs/forgejo.md: comprehensive setup guide (prerequisites, quick start, platform detection, GitHub differences, CI workflows, upstream merge process, known limitations, troubleshooting) - Updated README.md with Forgejo support mention and docs link - Updated CLAUDE.md with Forgejo architecture section - Added platform input to docs/usage.md inputs table - Added 5 Forgejo FAQ entries to docs/faq.md - Upstream merge validated: zero conflicts (based on latest upstream) - PRD #1 100% complete: all milestones M1-M9 done, 794 tests passing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
232 lines
10 KiB
Markdown
232 lines
10 KiB
Markdown
# Forgejo Platform Support
|
|
|
|
This action supports [Forgejo](https://forgejo.org/) (and Forgejo Actions) as an alternative to GitHub. The same action code runs on both platforms — platform detection is automatic or explicitly configured.
|
|
|
|
## Prerequisites
|
|
|
|
- **Forgejo instance** with [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/) enabled
|
|
- **Forgejo runner** registered and operational (e.g., a `grunt` or `ubuntu-latest` runner)
|
|
- **Anthropic API key** or **Claude Code OAuth token** for Claude API access
|
|
- **Forgejo token** with repo access (automatically available as `github.token` in workflows, or use a dedicated token)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Add Secrets
|
|
|
|
In your Forgejo repository, go to **Settings > Actions > Secrets** and add:
|
|
|
|
- `ANTHROPIC_API_KEY` — Your Anthropic API key (starting with `sk-ant-`)
|
|
|
|
If you need a dedicated token for Claude's GitHub operations (recommended for tag mode):
|
|
|
|
- `FORGEJO_CLAUDE_TOKEN` — A Forgejo personal access token with `repo` scope
|
|
|
|
### 2. Create Workflow
|
|
|
|
Create `.forgejo/workflows/claude.yml`:
|
|
|
|
```yaml
|
|
name: Claude Assistant
|
|
on:
|
|
issue_comment:
|
|
types: [created]
|
|
pull_request_review_comment:
|
|
types: [created]
|
|
issues:
|
|
types: [opened, assigned, labeled]
|
|
pull_request_review:
|
|
types: [submitted]
|
|
|
|
jobs:
|
|
claude-response:
|
|
runs-on: grunt # Your Forgejo runner label
|
|
steps:
|
|
- uses: https://git.wxs.ro/actions/claude-code-action@v1 # Or your mirror URL
|
|
with:
|
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
platform: "forgejo"
|
|
github_token: ${{ secrets.FORGEJO_CLAUDE_TOKEN }}
|
|
```
|
|
|
|
### 3. Agent Mode (Automation)
|
|
|
|
For automation workflows triggered by `workflow_dispatch`, push events, or schedules:
|
|
|
|
```yaml
|
|
name: Claude Automation
|
|
on:
|
|
workflow_dispatch:
|
|
inputs:
|
|
task:
|
|
description: "Task for Claude"
|
|
required: true
|
|
|
|
jobs:
|
|
run-claude:
|
|
runs-on: grunt
|
|
steps:
|
|
- uses: https://git.wxs.ro/actions/claude-code-action@v1
|
|
with:
|
|
prompt: ${{ github.event.inputs.task }}
|
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
platform: "forgejo"
|
|
github_token: ${{ secrets.FORGEJO_CLAUDE_TOKEN }}
|
|
```
|
|
|
|
## Platform Detection
|
|
|
|
The action detects the platform using a three-tier strategy:
|
|
|
|
| Priority | Method | Details |
|
|
| -------- | --------------------------------- | -------------------------------------------------------- |
|
|
| 1 | **Explicit input** | `platform: "forgejo"` in workflow — most reliable |
|
|
| 2 | **`FORGEJO` env var** | Set to `"true"` by Forgejo runner v7.0+ |
|
|
| 3 | **`GITHUB_SERVER_URL` heuristic** | If the URL doesn't contain `github.com`, assumes Forgejo |
|
|
|
|
**Recommendation**: Always set `platform: "forgejo"` explicitly. Auto-detection works but the explicit input eliminates ambiguity.
|
|
|
|
## Differences from GitHub
|
|
|
|
### Authentication
|
|
|
|
| Aspect | GitHub | Forgejo |
|
|
| ------------------------ | ------------------------------- | --------------------------------------- |
|
|
| **Default auth** | GitHub App OIDC token exchange | Direct `GITHUB_TOKEN` / `FORGEJO_TOKEN` |
|
|
| **Token setup** | Automatic via Claude GitHub App | Manual — provide `github_token` input |
|
|
| **App token revocation** | Automatic cleanup step | Skipped (no app token) |
|
|
| **Bot identity** | `claude[bot]` (ID: 41898282) | Token owner's identity |
|
|
|
|
On Forgejo, there is no OIDC token exchange with Anthropic. The action uses the workflow token (`github.token`) or a user-provided `github_token` directly.
|
|
|
|
### API Differences
|
|
|
|
| Feature | GitHub | Forgejo |
|
|
| --------------------- | ------------------------------------------- | ------------------------------------------------------------------- |
|
|
| **GraphQL API** | Used for PR/issue data fetching | Not available — REST API only |
|
|
| **Data fetching** | Single GraphQL query per entity | 5-8 parallel REST API calls |
|
|
| **Actor validation** | Checks for bot/app accounts | Skipped — no bot accounts on Forgejo |
|
|
| **GitHub MCP server** | `ghcr.io/github/github-mcp-server` included | Skipped — GitHub-specific |
|
|
| **CI/Actions MCP** | Full GitHub Actions API | Works via Octokit REST + `GITHUB_API_URL` |
|
|
| **Permission check** | `getCollaboratorPermissionLevel()` | `repos.get()` fallback (workflow tokens lack collaborator endpoint) |
|
|
|
|
### Bun Installation
|
|
|
|
The upstream action uses `oven-sh/setup-bun`. On Forgejo, this is replaced with a universal `curl` install because Forgejo runners pre-fetch all `uses:` action references before evaluating `if:` conditions, causing failures for GitHub-hosted actions that aren't mirrored.
|
|
|
|
### Comment URLs
|
|
|
|
Comment tracking URLs (job links, branch links, PR creation links) use Forgejo URL patterns instead of GitHub patterns. This is handled automatically.
|
|
|
|
## Action Inputs
|
|
|
|
The `platform` input is the only Forgejo-specific addition:
|
|
|
|
```yaml
|
|
platform:
|
|
description: "Platform to run on: 'auto' (default auto-detects), 'github', or 'forgejo'"
|
|
required: false
|
|
default: "auto"
|
|
```
|
|
|
|
All other inputs work identically on both platforms. See the [Usage Guide](./usage.md) for the full list.
|
|
|
|
## Included CI Workflows
|
|
|
|
This fork includes three Forgejo-native workflows in `.forgejo/workflows/`:
|
|
|
|
### `ci.yml` — Tests, Formatting, Type Checking
|
|
|
|
Runs on push to `main` and pull requests. Three parallel jobs:
|
|
|
|
- `test` — `bun test` (with `GITHUB_SERVER_URL` override so GitHub-context unit tests pass)
|
|
- `prettier` — `bun run format:check`
|
|
- `typecheck` — `bun run typecheck`
|
|
|
|
### `test-action.yml` — Action Self-Test
|
|
|
|
Tests the action itself on Forgejo in agent mode. Runs weekly and on PRs that modify `src/`, `action.yml`, or `.forgejo/`. Validates:
|
|
|
|
- Platform detection returns "forgejo"
|
|
- Token authentication works
|
|
- Claude Code executes successfully
|
|
- Output file is produced
|
|
|
|
### `upstream-sync.yml` — Upstream Sync Check
|
|
|
|
Runs weekly. Compares `main` with `upstream/main` (anthropics/claude-code-action). If upstream has new commits:
|
|
|
|
- Creates or updates an issue with the `upstream-sync` label
|
|
- Includes commit log, diff stats, and merge instructions
|
|
- Lists conflict-prone files
|
|
|
|
## Merging Upstream Changes
|
|
|
|
This fork is designed for easy upstream merges. Only 4-5 files have Forgejo-specific modifications, and changes are placed at function entry points using an early-return pattern.
|
|
|
|
### Merge Process
|
|
|
|
```bash
|
|
# Fetch latest upstream
|
|
git fetch upstream main
|
|
|
|
# Merge into your main branch
|
|
git merge upstream/main
|
|
|
|
# If conflicts occur, they'll be in these files:
|
|
# - src/entrypoints/run.ts (platform branch at top)
|
|
# - src/modes/tag/index.ts (data fetcher swap)
|
|
# - src/mcp/install-mcp-server.ts (platform routing)
|
|
# - action.yml (platform input, bun install)
|
|
|
|
# Resolve conflicts, keeping both the upstream changes and
|
|
# the Forgejo platform branches at function entry points
|
|
|
|
# Run tests to verify
|
|
bun test
|
|
|
|
# Push
|
|
git push origin main
|
|
```
|
|
|
|
### Conflict Mitigation
|
|
|
|
All Forgejo changes follow the **early-return pattern** — platform-specific logic is placed at the top of functions, before the existing GitHub code. This means:
|
|
|
|
- Upstream changes to the GitHub code path rarely conflict with Forgejo additions
|
|
- When conflicts do occur, they're localized to the few lines where the platform branch starts
|
|
- Resolution is straightforward: keep both the platform check and the upstream changes
|
|
|
|
### What Happens When Upstream Adds New Features
|
|
|
|
New upstream features that use GraphQL or GitHub-specific APIs won't automatically work on Forgejo. The Forgejo data fetcher (`src/forgejo/data/fetcher.ts`) would need REST equivalents added. The action will still run — features that depend on missing data will simply lack that context.
|
|
|
|
## Known Limitations
|
|
|
|
- **Tag mode (issue/PR triggers)**: Code is wired but only agent mode (workflow_dispatch) has been E2E tested on Forgejo. Tag mode should work but hasn't been validated with real issue/PR webhooks yet.
|
|
- **`pull_request_target` event**: May not exist in Forgejo. The action degrades gracefully (maps to `pull_request`).
|
|
- **GitHub MCP server**: The `ghcr.io/github/github-mcp-server` Docker image is GitHub-specific and is skipped on Forgejo.
|
|
- **Commit signing**: SSH signing has not been tested on Forgejo. The `use_commit_signing` option (GitHub API signing) won't work since it uses GitHub's commit API.
|
|
- **`downloadJobLogForWorkflowRun`**: Forgejo's Actions API may lack this endpoint. The CI MCP server attempts it via Octokit REST but may return limited data.
|
|
- **Bot filtering**: `allowed_bots` checks won't match `claude[bot]` since Forgejo has no bot accounts. Actor validation is skipped entirely on Forgejo.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Resource not accessible by integration" errors
|
|
|
|
This usually means the token lacks permissions. On Forgejo:
|
|
|
|
- Use a personal access token with `repo` scope via the `github_token` input
|
|
- The default `github.token` in Forgejo workflows may have limited permissions depending on your runner configuration
|
|
|
|
### Tests fail with platform detection errors
|
|
|
|
Unit tests assume GitHub context by default. When running on a Forgejo runner, set `GITHUB_SERVER_URL=https://github.com` before running tests (the CI workflow handles this automatically).
|
|
|
|
### Bun installation fails
|
|
|
|
If `curl -fsSL https://bun.sh/install | bash` fails on your runner, pre-install Bun on the runner image or use the `path_to_bun_executable` input to point to a custom Bun binary.
|
|
|
|
### Upstream workflows run and fail
|
|
|
|
If `.github/workflows/` from upstream are executing on your Forgejo runner, configure the runner to only read from `.forgejo/workflows/`. This is a runner-level setting — see your Forgejo instance's runner configuration.
|