Skip to content

feat(tools/forgejo): add Forgejo/Gitea adapter bridge (#310) - #1469

Open
Kaap10 wants to merge 1 commit into
apache:mainfrom
Kaap10:feat/tools-forgejo-310
Open

Kaap10 wants to merge 1 commit into
apache:mainfrom
Kaap10:feat/tools-forgejo-310

Conversation

@Kaap10

@Kaap10 Kaap10 commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add full tools/forgejo/ adapter fulfilling contract:tracker, contract:source-control, and contract:change-request for self-hosted and community Forgejo / Gitea instances.
  • Provide canonical tea CLI operational recipes with direct REST API fallbacks utilizing $TEA_TOKEN (avoiding forbidden shell command substitutions like $(...)).
  • Document REST-only project boards with explicit [!WARNING] callouts against GraphQL (since Forgejo does not support GitHub Projects V2 GraphQL).
  • Update adapter registry, capability taxonomy, labeler mappings, and vendor neutrality documentation.

Type of change

  • Tool / bridge contract (tools/<system>/*.md)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • CI / dev loop (prek, workflows, validators)

Test plan

  • All 8 new markdown files verified for SPDX Apache-2.0 license headers and generated doctoc TOC blocks.
  • Schema & capability validation verified with skill-and-tool-validator.
  • Vendor neutrality score verified (contract:tracker = 5 vendors, contract:source-control = 6 vendors, contract:change-request = 4 vendors).
  • Checked that no forbidden subshells ($(...)) or hallucinated GraphQL calls are documented.

RFC-AI-0004 compliance

  • HITL — any new mutation is gated on explicit user confirmation
  • Sandbox — no new unrestricted host access; network reach declared in the adapter (TEA_TOKEN env var, no interactive login prompts or subshells)
  • Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used throughout
  • Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
  • Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
  • Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Closes #310

Notes for reviewers (optional)

  • Standard REST API for Forgejo labels requires integer IDs; hence tea CLI is prioritized as the primary operational surface for simplicity and robustness, with explicit REST fallbacks documented.
  • Project board mutations are strictly restricted to REST endpoints (/api/v1/repos/{owner}/{repo}/projects), and agents are explicitly guarded against attempting GraphQL queries.

- Add tools/forgejo adapter satisfying contract:tracker, contract:source-control, and contract:change-request

- Document tea CLI and REST operations with $TEA_TOKEN auth fallback

- Add REST-only project-board guide with explicit warnings against GraphQL

- Update adapter registry, label taxonomy, and vendor neutrality score docs
@Kaap10
Kaap10 force-pushed the feat/tools-forgejo-310 branch from 26caccb to 7b2d0f6 Compare September 29, 2026 05:24
@github-actions github-actions Bot added contract:tracker Tool capability: issue / board / label backend contract:source-control Tool capability: branch / commit / diff / push (VCS) contract:change-request Tool capability: proposed-change review + merge gate (PR / MR / Gerrit change) labels Sep 29, 2026
@Kaap10

Kaap10 commented Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

Ready for review!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contract:change-request Tool capability: proposed-change review + merge gate (PR / MR / Gerrit change) contract:source-control Tool capability: branch / commit / diff / push (VCS) contract:tracker Tool capability: issue / board / label backend

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(tools/forgejo): forge + tracker bridge for Codeberg / Gitea / Forgejo

1 participant