gitea-infrastructure/lessons-learned.md

Lessons Learned

Session: 2026-02-18 -- Gitea Agent Skill Implementation

Technical Discoveries

1. Gitea 1.22.6 has no project board REST API

   • /api/v1/user/projects returns 404
   • The existing SKILL.md had endpoints that do not exist
   • Project board API is tracked in Gitea issue #14299, targeted for 1.26+
   • Mitigation: Use milestones as project containers -- they have built-in progress tracking

2. Scoped label exclusivity is UI-only in Gitea 1.22.6

   • Labels with exclusive: true display mutual exclusivity in the web UI
   • The API POST /repos/{owner}/{repo}/issues/{index}/labels only appends -- it does NOT remove conflicting scoped labels
   • Fix: Use a swap pattern: GET current labels, filter out old scope, add new label ID, PUT full set atomically
   • This was the single biggest "gotcha" -- the documentation implies API enforcement that does not exist

3. POST /issues/{index}/assignees does not exist in Gitea 1.22.6

   • Returns 404
   • Fix: Use PATCH /repos/{owner}/{repo}/issues/{index} with {"assignees": ["username"]}
   • This is a general issue edit endpoint, not a dedicated assignee endpoint

4. Issue dependency format is IssueMeta, not simple ID

   • Wrong: {"depends_on_id": 2} -- returns "repository does not exist [id: 0]"
   • Correct: {"owner": "terraphim", "repo": "agent-tasks", "index": 2}
   • Must check the Swagger spec for exact body format rather than guessing

Debugging Approaches That Worked

1. Test against live API first, then write code

   • Verified all 7 open questions against the live Gitea instance before writing any helper functions
   • This caught the project board API gap before writing fake endpoints

2. Integration tests with real cleanup

   • Each test run creates a timestamped repo (skill-test-{timestamp}), runs all tests, then deletes it
   • Trap on EXIT ensures cleanup even on failure
   • No mocks -- tests prove the actual API behavior

3. Incremental testing (run, fail, fix, rerun)

   • First test run: 23/26 pass, 3 fail -- immediately identified the label/assignee issues
   • Fixed the swap pattern and PATCH approach, second run: 26/26 pass

Pitfalls to Avoid

1. Do not trust Gitea documentation for API behavior -- always verify against the live instance. The swagger spec is the source of truth, but even that can be misleading for edge cases like scoped label exclusivity.

2. Do not assume POST endpoints exist for every resource subpath -- Gitea's API is inconsistent. Some resources (labels) have POST, others (assignees) only work via PATCH on the parent resource.

3. Do not rely on UBS scanner for infrastructure projects -- UBS found no scannable language files (expected for a project with only shell scripts, YAML, and markdown). Pre-commit hooks are more useful here.

4. Pre-commit python version -- The system may not have the Python version specified in .pre-commit-config.yaml. Changed from python3.9 to python3.12 to match the system. Also needed python3.12-venv apt package for virtualenv support.

Best Practices Discovered

1. Disciplined development phases work well for API integration

   • Phase 1 (Research): Discovered the project board API gap before design
   • Phase 2 (Design): Created the label swap architecture before implementation
   • Phase 3 (Implementation): Tests caught 3 API bugs on first run

2. Default repository pattern -- Using env vars with defaults (GITEA_OWNER=${GITEA_OWNER:-terraphim}) lets agents work out of the box while remaining configurable.

3. JSON output from all helpers -- Every shell function outputs valid JSON, making it trivial for agents to parse results with jq.

4. Idempotent setup scripts -- setup-labels.sh checks for existing resources before creating, making it safe to run repeatedly.