From c88782bd209d43e8fab7a57fcb673d1be25e39f5 Mon Sep 17 00:00:00 2001 From: Vlad Mocanu Date: Wed, 25 Feb 2026 20:06:47 +0200 Subject: [PATCH] docs: update Forgejo docs with tag mode E2E results - Add E2E Test Results section with validated capabilities - Document git ref API difference (refs vs ref) in Known Limitations - Document user display name 403 fallback - Add git ref lookup row to API differences table - Add claude.yml workflow to CI workflows section - Remove outdated "not yet E2E tested" note from tag mode Co-Authored-By: Claude Opus 4.6 --- docs/forgejo.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/forgejo.md b/docs/forgejo.md index 9b771cf..d445d5a 100644 --- a/docs/forgejo.md +++ b/docs/forgejo.md @@ -108,6 +108,7 @@ On Forgejo, there is no OIDC token exchange with Anthropic. The action uses the | **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) | +| **Git ref lookup** | `git.getRef()` (`/git/ref/heads/...`) | `repos.getBranch()` (`/git/refs` is plural on Forgejo) | ### Bun Installation @@ -132,7 +133,11 @@ All other inputs work identically on both platforms. See the [Usage Guide](./usa ## Included CI Workflows -This fork includes three Forgejo-native workflows in `.forgejo/workflows/`: +This fork includes four Forgejo-native workflows in `.forgejo/workflows/`: + +### `claude.yml` — Tag Mode (@claude Mentions) + +Responds to `@claude` mentions on issues, PR review comments, and PR reviews. Also triggers on issue assignment and label events. This is the main interactive workflow for using Claude on Forgejo. ### `ci.yml` — Tests, Formatting, Type Checking @@ -200,9 +205,36 @@ All Forgejo changes follow the **early-return pattern** — platform-specific lo 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. +## E2E Test Results + +Both execution modes have been validated end-to-end on a Forgejo instance (git.wxs.ro): + +| Mode | Trigger | Status | Details | +| -------------- | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Agent mode** | `workflow_dispatch` | Validated | Platform detection, token auth, Claude execution, output file — all green | +| **Tag mode** | `issue_comment` (`@claude`) | Validated | Issue context (title + body) read correctly, platform detected as `forgejo`, tracking comment created with spinner then updated with response (31s), job link URL correct | + +### Tag Mode Verified Capabilities + +- `@claude` trigger phrase detected in issue comments +- Issue body and title fully visible to Claude +- Tracking comment created with progress spinner, then updated with final response +- Forgejo job run URL correctly formatted in tracking comment +- Branch creation works via `repos.getBranch()` API (Forgejo uses `/git/refs` not `/git/ref`) +- Permission check passes via `repos.get()` fallback + +### Not Yet E2E Tested + +- PR review comment triggers (`pull_request_review_comment`) +- PR review triggers (`pull_request_review`) +- Label triggers (`issues` with `labeled` action) +- Assignee triggers (`issues` with `assigned` action) +- Branch creation + code changes from tag mode (issue asked a question, no code changes needed) + ## 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. +- **Git ref API**: Forgejo uses `/git/refs` (plural) instead of GitHub's `/git/ref` (singular). The action handles this by using `repos.getBranch()` on Forgejo for branch SHA lookups. +- **User display name fetch**: `GET /users/{username}` returns 403 without `read:user` scope. Non-fatal — falls back to login name. - **`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.