From 44f598ff119f3fc3f690a8eee6ff2e91d97bd63d Mon Sep 17 00:00:00 2001 From: Vlad Mocanu Date: Wed, 25 Feb 2026 19:55:25 +0200 Subject: [PATCH] feat(prd-1): complete M9 - documentation & upstream merge validation - 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 --- CLAUDE.md | 24 +++ README.md | 4 +- docs/faq.md | 22 +++ docs/forgejo.md | 231 +++++++++++++++++++++++++++++ docs/usage.md | 1 + prds/1-forgejo-platform-support.md | 6 +- 6 files changed, 285 insertions(+), 3 deletions(-) create mode 100644 docs/forgejo.md diff --git a/CLAUDE.md b/CLAUDE.md index 6c636bd..5a13296 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,30 @@ Single entrypoint: `src/entrypoints/run.ts` orchestrates everything — prepare - **`action.yml` outputs reference step IDs**: Outputs like `execution_file`, `branch_name`, `github_token` reference `steps.run.outputs.*`. If you rename the step ID, update the outputs section too. - **Integration testing** happens in a separate repo (`install-test`), not here. The tests in this repo are unit tests. +## Forgejo Platform Support + +This fork adds Forgejo support via a lean adapter pattern — only 4 genuinely different areas have Forgejo-specific code: + +- **`src/platform/detector.ts`** — Three-tier platform detection (explicit input > `FORGEJO` env > `GITHUB_SERVER_URL` heuristic) +- **`src/forgejo/token.ts`** — Direct token handling (skips OIDC exchange) +- **`src/forgejo/data/fetcher.ts`** — REST-based data fetching (replaces 3 GraphQL queries with 5-8 parallel REST calls) +- **`src/forgejo/comment-logic.ts`** — Forgejo URL patterns for tracking comments + +All other `src/github/` modules work on Forgejo via Octokit REST as-is (permissions, comments, branches, git config, context, formatter). + +**Key integration points** (these files have platform branches and are merge-conflict surface): + +- `src/entrypoints/run.ts` — Platform branch at top for token setup +- `src/modes/tag/index.ts` — Data fetcher swap (`fetchForgejoData` vs `fetchGitHubData`) +- `src/github/operations/comments/create-initial.ts` — Platform-aware spinner/URL format +- `src/github/operations/comments/update-with-branch.ts` — Forgejo PR compare URL +- `src/github/validation/actor.ts` — Skipped on Forgejo (no bot accounts) +- `src/mcp/install-mcp-server.ts` — Skips GitHub public MCP server on Forgejo + +**MCP server names stay the same** (`github_comment`, `github_ci`, etc.) even on Forgejo — changing them would require updating hardcoded tool name lists in `src/modes/tag/index.ts`. + +**CI**: `.forgejo/workflows/` contains `ci.yml`, `test-action.yml`, and `upstream-sync.yml`. Unit tests run with `GITHUB_SERVER_URL=https://github.com` override on Forgejo runners. + ## Code Conventions - Runtime is Bun, not Node. Use `bun test`, not `jest`. diff --git a/README.md b/README.md index b8301f7..67a52f7 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Claude Code Action -A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs and issues that can answer questions and implement code changes. This action intelligently detects when to activate based on your workflow context—whether responding to @claude mentions, issue assignments, or executing automation tasks with explicit prompts. It supports multiple authentication methods including Anthropic direct API, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry. +A general-purpose [Claude Code](https://claude.ai/code) action for GitHub and Forgejo PRs and issues that can answer questions and implement code changes. This action intelligently detects when to activate based on your workflow context—whether responding to @claude mentions, issue assignments, or executing automation tasks with explicit prompts. It supports multiple authentication methods including Anthropic direct API, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry. ## Features @@ -16,6 +16,7 @@ A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs an - 📊 **Structured Outputs**: Get validated JSON results that automatically become GitHub Action outputs for complex automations - 🏃 **Runs on Your Infrastructure**: The action executes entirely on your own GitHub runner (Anthropic API calls go to your chosen provider) - ⚙️ **Simplified Configuration**: Unified `prompt` and `claude_args` inputs provide clean, powerful configuration aligned with Claude Code SDK +- 🔀 **Forgejo Support**: Runs on [Forgejo](https://forgejo.org/) with automatic platform detection — same action, same features, different git host ## 📦 Upgrading from v0.x? @@ -60,6 +61,7 @@ Each solution includes complete working examples, configuration details, and exp - [Cloud Providers](./docs/cloud-providers.md) - AWS Bedrock, Google Vertex AI, and Microsoft Foundry setup - [Capabilities & Limitations](./docs/capabilities-and-limitations.md) - What Claude can and cannot do - [Security](./docs/security.md) - Access control, permissions, and commit signing +- [Forgejo Setup](./docs/forgejo.md) - Running on Forgejo instances with platform detection and REST-only APIs - [FAQ](./docs/faq.md) - Common questions and troubleshooting ## 📚 FAQ diff --git a/docs/faq.md b/docs/faq.md index b491343..a78f149 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -251,6 +251,28 @@ For specialized environments like Nix, NixOS, or custom container setups where y - The action will skip automatic installation when custom paths are provided - Ensure the custom executables are available in your GitHub Actions environment +## Forgejo-Specific Questions + +### Can I use this action on Forgejo? + +Yes. Set `platform: "forgejo"` in your workflow and provide a `github_token` with repo access. See the [Forgejo Setup Guide](./forgejo.md) for complete instructions. + +### Why is GraphQL not used on Forgejo? + +Forgejo doesn't have a GraphQL API. The action uses parallel REST API calls instead, which provides the same data with slightly more HTTP requests. This is handled automatically — no configuration needed. + +### Why is actor validation skipped on Forgejo? + +Forgejo has no bot or app accounts, so the bot/app check that GitHub uses is unnecessary. Additionally, the `read:user` scope required for `getByUsername()` isn't available with standard Forgejo workflow tokens. + +### Why does `oven-sh/setup-bun` fail on my Forgejo runner? + +Forgejo runners pre-fetch all `uses:` action references before evaluating `if:` conditions. If `oven-sh/setup-bun` isn't mirrored to your Forgejo instance, the prefetch fails even when the step would be skipped. This fork replaces it with a universal `curl` install that works on both platforms. + +### How do I keep my Forgejo fork in sync with upstream? + +The included `upstream-sync.yml` workflow runs weekly and creates an issue when upstream has new commits. It includes merge instructions and lists the conflict-prone files. See [Merging Upstream Changes](./forgejo.md#merging-upstream-changes). + ## Best Practices 1. **Always specify permissions explicitly** in your workflow file diff --git a/docs/forgejo.md b/docs/forgejo.md new file mode 100644 index 0000000..9b771cf --- /dev/null +++ b/docs/forgejo.md @@ -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. diff --git a/docs/usage.md b/docs/usage.md index 3e55a3d..cc8ec24 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -81,6 +81,7 @@ jobs: | `path_to_bun_executable` | Optional path to a custom Bun executable. Skips automatic Bun installation. Useful for Nix, custom containers, or specialized environments | No | "" | | `plugin_marketplaces` | Newline-separated list of Claude Code plugin marketplace Git URLs to install from (e.g., see example in workflow above). Marketplaces are added before plugin installation | No | "" | | `plugins` | Newline-separated list of Claude Code plugin names to install (e.g., see example in workflow above). Plugins are installed before Claude Code execution | No | "" | +| `platform` | Platform to run on: `auto` (default, auto-detects), `github`, or `forgejo`. See [Forgejo Setup](./forgejo.md) | No | `auto` | ### Deprecated Inputs diff --git a/prds/1-forgejo-platform-support.md b/prds/1-forgejo-platform-support.md index 3d3ce0e..8484db9 100644 --- a/prds/1-forgejo-platform-support.md +++ b/prds/1-forgejo-platform-support.md @@ -291,9 +291,11 @@ The upstream repo has 13 workflows in `.github/workflows/`. Strategy: - Depends on: M7 - Success: Agent mode works on Forgejo. Self-test workflow passes. CI tests pass. Note: tag mode (issue trigger, PR review) not yet E2E tested — code paths are wired but await real-world validation. -- [ ] **M9: Documentation & upstream merge validation** — Document Forgejo-specific setup (runner configuration, token setup, `platform: forgejo` input). Create `CLAUDE.md` for the project. Perform a fresh `git fetch upstream && git merge upstream/main` to verify conflicts are minimal and easily resolvable. Document the merge process. +- [x] **M9: Documentation & upstream merge validation** — Created comprehensive `docs/forgejo.md` setup guide covering prerequisites, quick start (tag + agent mode), platform detection, GitHub vs Forgejo differences (auth, API, bun install, comment URLs), CI workflows, upstream merge process with conflict mitigation, known limitations, and troubleshooting. Updated `README.md` (Forgejo in description, feature bullet, docs link), `CLAUDE.md` (Forgejo architecture section with key files and integration points), `docs/usage.md` (`platform` input in table), `docs/faq.md` (5 Forgejo FAQ entries). Upstream merge validation: `git merge upstream/main` → zero conflicts — branch based on latest upstream `ade221f`. All 794 tests pass. + + - Files: `docs/forgejo.md` (NEW), `README.md` (MODIFIED), `CLAUDE.md` (MODIFIED), `docs/usage.md` (MODIFIED), `docs/faq.md` (MODIFIED) - Depends on: M8 - - Success: Clean or trivially-resolvable upstream merge. Clear setup docs. + - Success: Zero-conflict upstream merge. Complete Forgejo setup documentation with troubleshooting guide. ### Milestone Dependency Graph