public/claude-code-action
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(prd-1): complete M9 - documentation & upstream merge validation

Browse Source 
- 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>
This commit is contained in:
Vlad MocanuandClaude Opus 4.6 committed 2026-02-25 19:55:25 +02:00
1 parent 5daed4f9bf
commit 44f598ff11
6 files changed
+285 -3
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/forgejo.md
+231
View File
@@ -0,0 +1,231 @@
# 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.