248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
---
|
|
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`
|
|
- public routing mode: `port-based` or `virtual-host`
|
|
- websocket public entry: explicit WS URL (`wss://...`) or same-origin path (`/ws`)
|
|
- 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.
|
|
|
|
### Routing Strategy (Recommended)
|
|
|
|
- Prefer `virtual-host` over raw ports for multi-branch testing:
|
|
- `main.example.com`, `preview-a.example.com`, `preview-b.example.com`
|
|
- Keep internal process ports private; expose only 80/443.
|
|
- Use same-origin WS path for frontend (`VITE_WS_URL=/ws`) and route `/ws/*` to the slot server.
|
|
- If `port-based` is used, every active env must have unique client/server ports; never reuse one public URL for two branches.
|
|
|
|
## 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.
|
|
- Verify websocket handshake is healthy on the published preview URL/path before asking QA to test.
|
|
- 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.
|
|
- When changing public service ports under PM2, do not rely on `pm2 restart --update-env` alone; delete and recreate the process so CLI args (for example `--port`) actually change.
|
|
- If a branch must be rebound to a specific preview slot (for example `preview-a`), release the existing issue allocation first, then redeploy; reuse logic otherwise keeps the previous slot by design.
|