devops-skills/skills/gitea-issue-devops-agent/SKILL.md

name, description

name

description

gitea-issue-devops-agent

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.