Skip to content

Gitea/Forgejo adapter — generator dogfood candidate #2952

Closed

Description

@kyle-sexton

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened).

What to build

An adapter for Gitea/Forgejo (free, self-hostable, GitHub-shaped API) — deliberately built AS the first dogfood of the adapter-onboarding skill rather than hand-written: run the generator against a live Gitea/Forgejo instance, let it interview + explore + generate + conformance-verify, and treat every gap it hits as a finding against the generator. Serves the no-paid-tool constraint for solo devs and validates the hybrid shipping model end-to-end. Capability honesty required where the API diverges from GitHub (native sub-issues/dependencies differ by version — gate, don't fake).

Acceptance criteria

  • Adapter generated (not hand-written) via the onboarding skill, passing conformance with honest capability gating
  • Generator findings from the run filed back against the onboarding skill
  • Setup skill's provider comparison updated

Blocked by

Activity

  1. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Aug 17, 2026
  2. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Aug 17, 2026
  3. kyle-sexton commented on Aug 20, 2026

    @kyle-sexton
    MemberAuthor

    Status: adapter generated and offline-verified; live conformance blocked

    Landed on claude/pocock-shipping-breakdown-ukohlx (8a5a8950).

    Against the acceptance criteria

    • [~] Adapter generated (not hand-written) via the onboarding skill, passing conformance with
      honest capability gating.
      Generated — the scaffolds, security skeleton, manifest, conformance
      binding, and both generated test suites all came out of
      /work-items:onboard-adapter's generator from adapters/gitea/adapter-spec.json; only the
      per-verb provider mappings were written by hand, which is the split the skill is built around.
      Capability gating is honest (below). Conformance against a live instance has NOT been run —
      see the blocker.
    • Generator findings from the run filed back against the onboarding skill. Four defects and
      two gaps, recorded on #2950
      and all fixed in the generator.
    • Setup skill's provider comparison updated. gitea is now a listed provider with its own
      row; the full comparison moved to skills/setup/reference/providers.md (the skill had reached
      its 500-line hard cap).

    Capability honesty

    Gated to exit 6, each for a stated reason rather than for convenience:

    Gated Why
    add-sub-item, list-sub-items Gitea's Issue has no parent field at all (modules/structs/issue.go). Structurally absent, not unmapped.
    claim, renew-lease, reclaim Gitea has the primitives the github lease is built from (assignees + comments), but whether concurrent assignment is arbitrated cannot be settled without a live instance and two identities. An emulated lease over last-write-wins loses races silently — worse than not having one.

    Consequence stated plainly rather than buried: /work-items:work cannot claim on gitea, so it is
    not a multi-agent coordination surface today. Enabling leases later is a manifest change plus three
    verb scripts; nothing else in the adapter assumes their absence.

    Divergences found (verified against the Gitea source, not assumed from GitHub's API)

    • A pull request IS an issue (pull_request populated). list-items drops them — a PR arriving
      as a work item would be selected and worked like one.
    • create-item takes label IDs, not names (CreateIssueOption.labels is []int64). The
      adapter resolves names against the repo's label set and refuses an unknown name rather than
      dropping it: an item filed without its type or priority label is invisible to the very selection
      tiers that would have picked it up.
    • blocked_by_count is N+1. The Issue carries no dependency data and there is no bulk
      endpoint. Returning 0 would be worse than slow — list-frontier filters on
      blocked_by_count == 0, so every blocked item would surface as available work.
    • Dependency direction: POST /issues/{index}/dependencies makes the URL issue depend on
      the body issue. The sibling /blocks endpoint is the same edge from the other end; using it
      would invert every edge, and the frontier would release exactly the items it should hold.
    • Cross-repo edges work but are instance-gated. ALLOW_CROSS_REPOSITORY_DEPENDENCIES defaults
      true and can be disabled, answering 400 CrossRepositoryDependencies not enabled; mapped to exit
      7 with the setting named.
    • No ceiling on dependencies — Gitea rejects only duplicate and circular edges. This is what
      forced limits to grow a null value.

    Blocker

    No Gitea or Forgejo instance is reachable from this environment. conformance/bindings/gitea.sh is
    written and refuses to run without an explicitly named throwaway target
    (WIT_CONFORMANCE_GITEA_HOST + WIT_CONFORMANCE_GITEA_SCOPE), so a destructive suite cannot fall
    back to a default. Until that pass happens, treat the live behaviour as
    documented-and-tested-against-the-documentation, not as verified — and Forgejo parity as assumed
    rather than measured.

    Left open for that reason.


    Generated by Claude Code

  4. kyle-sexton commented on Aug 21, 2026

    @kyle-sexton
    MemberAuthor

    Closing: descoped on the live-conformance criterion

    Maintainer scope call — "I don't think we need it, we just need linear." Closing on what shipped rather than leaving this open indefinitely against a criterion we've decided not to pursue.

    Gitea stays shipped and supported. The adapter merged in #3056 and remains the free, self-hostable option serving the no-paid-tool constraint this effort set for solo developers. What's descoped is validating it against a live server, not the adapter itself.

    Against the acceptance criteria, stated honestly

    • Adapter generated (not hand-written) via the onboarding skill — generated through /work-items:onboard-adapter as the designated dogfood.
    • Honest capability gating — add-sub-item, list-sub-items, claim, reclaim, renew-lease all declared false with sub_item_depth: 0, because Gitea has neither sub-issues nor a lease surface. No verb script exists for any false verb — the contract's declared-false-exits-6 gate handles them, so nothing is stubbed or faked to look supported.
    • Passing conformance — not met, descoped.
    • Generator findings from the run filed back — met in substance, and better than filing: four findings were found and fixed in the generator and its templates rather than deferred. A hardcoded sample id number (12) that would have failed on day one for any consumer with a different api.sample_id; a basic-auth auth_user baked to a placeholder with no override; the host_suffix domain-boundary bypass fixed in the shared template so every future generated adapter inherits it; and a quote_safe choke point the jira adapter never had.
    • Setup skill's provider comparison updated — verified present in skills/setup/SKILL.md and skills/setup/reference/providers.md.

    Correcting the blocker reason on record

    Earlier notes on this effort — including the adapter README — said no Gitea instance was reachable from the build environment. That was an untested assumption stated as fact, and it is false. Gitea ships as a single self-contained binary with sqlite built in, its releases are fetchable from that environment, and a real Gitea 1.22.6 was downloaded and version-verified there.

    The actual blocker is narrower: serving it needs privileged setup — a dedicated unprivileged user plus cap_net_bind_service, since Gitea declines to run as root — which the sandbox's permission policy gates. Reachability was never the constraint. Corrected in adapters/gitea/README.md and in the SSOT.

    Do not "unblock" this later by relaxing the host rule

    Port 443 and TLS are structural, not preferences: wit_gitea_http builds https://<host>/api/v1 under --proto '=https', and config.gitea.host must be a bare hostname, so a high port is not expressible. That rule exists so a PR-modifiable binding cannot smuggle URL structure and redirect the credential off the intended tenant. Widening it to make a suite run would trade a real security control for a green check.

    If a live pass is ever wanted: stand up a throwaway Gitea on 443 with TLS, set WIT_CONFORMANCE_GITEA_HOST / WIT_CONFORMANCE_GITEA_SCOPE / WIT_GITEA_TOKEN, and run conformance/run-conformance.sh --binding gitea. The binding is written and refuses to run without an explicitly named throwaway target.

    Full reasoning recorded durably in docs/upstream/aihero-shipping-course.md § "Adapter-track scope decision".


    Generated by Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.needs-triageNot yet classified. Floor until a type and one priority tier are set.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions