---
name: gitea-issue-devops-agent
description: End-to-end Gitea issue delivery workflow with guided onboarding, branch-scoped preview environments, and resource-aware deployment decisions. Use when tasks involve connecting to Gitea, processing text/image issues, fixing code on issue-specified branches, allocating/reusing test environments per branch, running test submission loops, coordinating review approvals, and closing issues only after verified delivery and engineer-confirmed merge.
---

# Gitea Issue DevOps Agent

## Mandatory Guided Start

Run this interaction before any coding or issue action:

1. Ask for repository address:
   - preferred: full URL `https://<host>/<owner>/<repo>`
   - fallback: `base_url` + `owner/repo`
2. Ask for API key/token with issue read/write permissions.
3. Ask user to select mode:
   - `automatic`
   - `semi-automatic`
   - `manual` (non-automatic)
4. Ask optional defaults:
   - designated reviewers (for semi-automatic mode)
   - branch test submission entrypoint (CI command/job)
   - environment policy:
     - stable main URL (`main` fixed test env)
     - optional shared QA URL
     - preview slot pool (for issue branches), e.g. `preview-a,preview-b`
     - preview URL template, e.g. `https://{slot}.qa.example.com`
   - deployment environment + health endpoint
   - minimum issue quality score (default `70`)
5. Validate connectivity by running:
   - `python scripts/issue_audit.py --repo <owner/repo> --base-url <gitea_url> --token <token> --state all --download-attachments --output-dir .tmp/issue-audit`
6. Initialize preview-slot state (if branch previews enabled):
   - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots <slot_csv> --list`
7. Echo back the selected mode and all gate rules, then start work.

If repository or token is missing/invalid, stop and request correction. Never start development without a successful connectivity check.

## Mode Definitions

### 1) Automatic Mode

- Read issue-specified branch and work on that branch.
- Implement fix, run checks, push branch, allocate/reuse branch preview env, and trigger branch test submission automatically.
- Monitor test results and issue feedback, then iterate on the same branch until pass.
- Close issue only after evidence is complete.
- Merge is still blocked until an engineer explicitly confirms merge approval.

### 2) Semi-Automatic Mode

- Read issue-specified branch and work on that branch.
- Implement and push fix.
- Notify designated reviewer with change summary, risk, and test plan.
- Wait for explicit human review approval.
- After approval, allocate/reuse branch preview env, trigger branch test submission and continue loop.
- Close issue only after evidence is complete.
- Merge is still blocked until an engineer explicitly confirms merge approval.

### 3) Manual Mode (Non-Automatic)

Require explicit human confirmation before each major action:

- selecting issue
- confirming target branch
- applying code changes
- pushing commits
- triggering tests/deploy
- closing/reopening issue
- executing merge

No autonomous transition is allowed in manual mode.

## Branch-First Rules

- Treat issue-declared branch as the source of truth.
- Accept branch hints from issue fields/body/comments (example: `branch: feat/login-fix`).
- If branch is missing or ambiguous, ask user/reporter and pause that issue.
- Do not silently switch branches.
- Keep one active issue per branch unless user explicitly approves batching.

## Environment Model (Required)

Always avoid `main` and issue branches overwriting each other.

1. `main` fixed env (stable):
   - one permanent URL for regression/baseline testing
2. optional shared QA env:
   - integration testing across multiple completed branches
3. issue preview slot env (ephemeral pool):
   - small fixed pool (`N` slots, e.g. 2)
   - one active branch binds to one slot
   - issue comments must include slot + URL + branch
   - close/merge/TTL expiry releases slot

Never deploy different branches to the same fixed URL unless user explicitly approves override.

## Issue -> Branch -> Environment Binding

- Binding key: `<repo>#<issue>#<branch>`
- Environment selection:
  - if branch already has assigned slot: reuse same slot
  - else allocate free slot from pool
  - if no free slot:
    - in `automatic`: evict oldest expired/inactive slot if policy allows
    - in `semi-automatic` / `manual`: request explicit confirmation before eviction
- Persist slot state in `.tmp/preview-slots.json` via `scripts/preview_slot_allocator.py`

## Resource-Aware Deployment Strategy (Required)

Before every branch test submission, detect change scope:

- `python scripts/change_scope.py --repo-path <local_repo> --base-ref <target_base> --head-ref <branch_or_sha>`

Use the scope result to minimize resource usage:

1. `skip` (docs/tests/chore-only):
   - do not deploy
   - post no-op verification evidence
2. `client_only`:
   - build/deploy client only
   - reuse existing shared/stable server
   - do not start a dedicated server for this branch
3. `server_only`:
   - deploy/restart server only
   - keep existing client if unchanged
4. `full_stack`:
   - deploy both client and server
5. `infra_only`:
   - apply infra/workflow changes; restart only required components

Hard rule:
- If server-related scope is unchanged, do not provision/restart dedicated server processes for that issue branch.

## Standard Workflow (All Modes)

### 1) Intake and Prioritization

- Pull issues, comments, and attachments from Gitea API.
- If issue text/comments indicate image evidence but `attachments_downloaded` is `0`, stop and report image-intake failure before coding.
- Prioritize in this order:
  - `closed_but_unresolved`
  - `open` + `quality_score >= min_quality_score`
  - `open` + `quality_score < min_quality_score` (request details first)
  - `closed_open_reopen_candidates`
- For issues with images, inspect attachments before coding.

### 2) Deduplication and Quality Gate

- Group issues by semantic intent, not literal wording.
- Keep one parent issue for implementation.
- Use `references/triage-standard.md` for score and comment templates.
- For low-quality issues, request details and mark as `needs-info`.

### 3) Fix Execution

- Prefer small, reversible patches.
- Link every code change to issue ID in commit or PR/MR notes.
- Split cross-cutting work into incremental commits.

### 4) Verification Gate

- Required:
  - build/compile passes
  - affected unit/integration tests pass
  - smoke path for reported scenario passes
- For UI/image issues:
  - compare before/after screenshots
  - verify in at least one Chromium browser

### 5) Branch Test Submission ("提测")

- Submit testing on the issue branch (CI pipeline + branch preview env).
- Allocate/reuse branch slot before submission.
- Apply resource-aware deployment decision from change scope.
- Post evidence in issue comment:
  - commit SHA
  - test run URL and result
  - environment/slot/URL
  - deployment scope (`skip`/`client_only`/`server_only`/`full_stack`/`infra_only`)
  - shared backend reused or dedicated backend started
  - verification steps
- If fail/reject, iterate on same branch and re-submit.

### 6) Loop Control

- Continue `fix -> test submission -> feedback -> fix` until done.
- Reopen immediately if verification fails or regression appears.
- Do not close based on title-only or assumption-only validation.

### 7) Closure Rule

Close issue only when all are true:

- root cause identified
- fix verified with reproducible evidence
- test submission passed
- closure comment includes commit/test/deploy evidence

### 8) Merge Rule (Always Human-Confirmed)

- Final merge must be approved by an engineer in all modes.
- Agent can prepare merge notes/checklist, but must wait for explicit merge confirmation.
- Merge only after confirmation, then post final release evidence.

### 9) Environment Cleanup

- On issue close/merge:
  - release preview slot
  - stop branch-only processes (if any)
  - keep main/shared env untouched
- On TTL expiry:
  - reclaim idle slot automatically (automatic mode) or after confirmation (semi/manual)

## Script Usage

- `scripts/issue_audit.py`: collect issues/comments/attachments, detect duplicates, score quality, detect unresolved/closed-open links, extract issue branch hints, and generate reports.
  - image intake uses three sources: markdown/html links, payload `assets/attachments` fields, and `/issues/*/assets` API endpoints.
  - if your Gitea blocks the assets endpoints, pass `--skip-asset-endpoints` and rely on payload extraction.
- `scripts/preview_slot_allocator.py`: allocate/reuse/release/list preview slots by issue+branch.
  - allocate example:
    - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots preview-a,preview-b --repo <owner/repo> --issue 48 --branch dev --ttl-hours 24 --url-template https://{slot}.qa.example.com`
  - release example:
    - `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots preview-a,preview-b --release --repo <owner/repo> --issue 48 --branch dev`
- `scripts/change_scope.py`: detect changed scope and recommend minimum deploy strategy.
  - `python scripts/change_scope.py --repo-path <repo> --base-ref origin/main --head-ref HEAD`
- `references/triage-standard.md`: scoring rubric and templates for needs-info, review request, test submission, and merge approval.

## Operational Constraints

- Never bulk-close issues without per-issue verification evidence.
- Never ignore attachment images for UI/interaction issues.
- Never merge feature requests and bugfixes into one untraceable commit.
- Never bypass engineer merge confirmation.
- Never allow branch previews to overwrite main stable env.
- Never start dedicated branch server when scope indicates client-only changes.