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

name, description

name	description
gitea-issue-devops-agent	Use when coordinating AI-assisted Gitea issue delivery where work must stay traceable across issue selection, branch or PR flow, CI/CD, preview environments, and human merge approval.

Gitea Issue DevOps Agent

Overview

Treat AI as a fast but unstable engineer. The public workflow must remain issue -> branch -> PR -> CI/CD -> human-confirmed merge, while the internal execution model must narrow context, persist plans, require verification evidence, and keep humans in control of final merge decisions.

This skill is platform-aware for Gitea, but its delivery contract must stay portable across basic DevOps primitives: git, issue, PR, and CI/CD.

Core Principles

• Start coding only from a selected issue, not from an unbounded issue queue, unless the user explicitly asks for triage-only queue scanning.
• Every delivery issue must have a persisted plan before any code changes.
• External collaboration stays Git-native: issue, branch, PR, pipeline, review app, merge.
• AI output is provisional until tests, smoke paths, and review evidence exist.
• Engineers stay in the loop from the initial PR onward and own white-box review.
• Keep one active issue per branch and per execution agent unless the user explicitly approves batching.

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 for the selected issue trigger source:
   • explicit issue number
   • issue comment / webhook trigger
   • app/CLI selection
   • triage-only queue scan without coding
5. Ask optional defaults:
   • target base branch (for example main, develop, protected release branch)
   • branch naming convention for issue branches
   • plan storage path (default .tmp/devops-plans/<repo>__issue-<number>.md)
   • issue template policy (required or recommended) for bug, enhancement, and feature
   • 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)
   • jj policy:
     • disabled
     • optional-internal
     • required-internal
6. 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
7. Initialize preview-slot state (if branch previews enabled):
   • python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots <slot_csv> --list
8. Echo back the selected mode, selected issue trigger, target base branch, plan path, jj policy, 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.

Issue Intake Contract (Required)

• Require issue templates for bug, enhancement, and feature. See references/issue-template-standard.md.
• A coding run must start from one fixed issue chosen by a human or an explicit trigger. Queue polling is for triage only unless the user explicitly enables unattended processing.
• If the selected issue is too broad for one reviewable PR, split it into sub-issues before coding.
• If issue quality is below threshold, request details and stop before branch creation.
• For image/UI issues, attachment intake is mandatory before implementation.

Plan-First Orchestration (Required)

Before any code change, the MajorAgent must create and persist a plan for the selected issue. Use references/plan-template.md.

Minimum plan fields:

• issue number and title
• trigger source and current issue status
• target base branch and working branch
• current problem description
• expected behavior and acceptance criteria
• related interfaces, services, and directories
• allowed file/path scope for edits
• verification steps, including issue-level e2e coverage
• assigned execution agent
• risk notes and blockers
• evidence links or placeholders for commit, PR, pipeline, and preview URL

Required status flow:

• selected
• planned
• in_progress
• pending_test
• pending_review
• merged
• closed
• needs_info
• blocked
• rejected

Hard rules:

• No code changes before the plan exists.
• No status promotion without evidence.
• If scope changes materially, update the plan before continuing.

Agent Role Separation (Required)

MajorAgent

• Pull issues, comments, and attachments from Gitea.
• Perform semantic triage and create the plan.
• Select or create the issue branch and initialize the PR.
• Decide whether work can proceed automatically or must pause for human input.

SubAgent (Developer)

• Load only the plan and the minimal code context needed for the issue.
• Modify code only within the allowed path scope unless explicit approval expands scope.
• Keep patches small and reversible.
• Update the plan to pending_test with a concise implementation summary.

TestAgent

• Load the plan, diff, and verification steps.
• Validate build, targeted tests, issue-level e2e path, and smoke path.
• Update the plan to pending_review only when evidence is complete.
• Reopen the plan to in_progress if failures or regressions appear.

Human Reviewer / Maintainer

• Review the draft PR and the plan evidence.
• Use the AI coding tool for follow-up adjustments if needed.
• Approve or reject final merge.

Mode Definitions

1) Automatic Mode

• Start only after a fixed issue has been selected and a plan has been created.
• Read or create the issue branch and open/update the draft PR automatically.
• 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

• Start only after a fixed issue has been selected and a plan has been created.
• Read or create the issue branch and open/update the draft PR.
• 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
• finalizing the plan
• confirming target branch
• creating or updating the PR
• 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 when provided.
• If the issue does not declare a branch, create one from the configured protected base branch after the plan is approved.
• Preferred naming pattern: <type>/issue-<number>-<slug> or issue/<number>-<slug>.
• 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.
• Open or update a draft PR immediately after branch selection so the review surface exists from the start.
• Keep issue, branch, PR, preview env, and plan bound together for the full lifecycle.

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) Issue Selection and Trigger

• Start from a fixed issue chosen through comment mention, webhook, app/CLI selection, or explicit human instruction.
• Repo-wide polling may be used for triage reports, but not for autonomous coding unless the user explicitly enables queue processing.

2) Intake and Prioritization

• Pull the selected issue, 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.

3) 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.

4) Plan Generation

• MajorAgent must generate a plan before branch creation or code changes.
• Persist the plan to the configured plan path and echo the summary back to the user.
• Record the allowed file/path scope so later diffs can be checked against it.
• Record the issue-level e2e scenario from the reporter's perspective.

5) Branch and PR Initialization

• Create or reuse the issue branch from the configured base branch.
• Create or update the associated draft PR targeting the protected integration branch.
• The PR body must include issue link, plan summary, intended file scope, and verification checklist.

6) 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.
• Do not modify files outside the allowed plan scope without explicit approval and a plan update.
• Any new dependency, framework, SDK, or major library change must be checked against official docs, maintenance status, and local compatibility before merge.
• Do not trust knowledge-base output as truth unless it has clear provenance and matches the current codebase.

7) Verification Gate

• Required:
  • build/compile passes
  • affected unit/integration tests pass
  • issue-level e2e test is added or updated and passes in the PR pipeline unless the user explicitly waives it
  • smoke path for reported scenario passes
• For UI/image issues:
  • compare before/after screenshots
  • verify in at least one Chromium browser
• If verification evidence is missing, do not claim the issue is fixed.

8) 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
  • PR URL
  • 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
  • e2e result
  • verification steps
• If fail/reject, iterate on same branch and re-submit.

9) 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.

10) Human Review and AI-Assisted Refinement

• From the initial PR onward, engineering review is the default path.
• Engineers may continue refinement inside an AI coding tool, but all follow-up work must stay on the same issue branch and update the same plan.
• Human review is the white-box gate between initial AI output and final merge readiness.

11) Closure Rule

Close issue only when all are true:

• root cause identified
• fix verified with reproducible evidence
• test submission passed
• PR review state is recorded
• closure comment includes commit/test/deploy evidence

12) 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.

13) 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)

AI Reliability Guardrails

• Evidence before assertions: never claim “fixed”, “tested”, or “deployed” without command output, screenshots, or links proving it.
• Diff-scope gate: compare the actual diff with the plan's allowed paths before PR update or merge request.
• Dependency gate: do not add new packages or major version upgrades without checking official documentation, maintenance state, and environment compatibility.
• Deprecated-tech gate: do not introduce deprecated or no-longer-recommended libraries/classes unless the user explicitly approves the trade-off.
• Context minimization: every execution agent should load the issue, plan, diff, and only the code areas it needs.
• No silent batching: do not mix unrelated fixes into one issue branch or PR.

Knowledge Context Policy

• Do not blindly vectorize or load the entire repository as context for each issue.
• Build a curated issue context pack consisting of:
  • issue body and comments
  • plan summary
  • touched directories and interfaces
  • related tests
  • relevant configuration and prior PR/commit references
• Record the chosen context sources in the plan so later agents can reuse them.
• Treat knowledge-base retrieval as a hint layer, not as a source of truth.

Jujutsu (jj) Integration Strategy (Optional but Recommended Internally)

jj should improve internal execution reliability, not replace the external Git workflow.

Use jj only under these rules:

• Keep Git branches, PRs, and CI/CD as the public system of record.
• Map the issue branch to a jj bookmark when jj is enabled.
• Use jj change IDs to support iterative rewrites without losing traceability.
• Use jj workspaces for parallel SubAgent/TestAgent/human adjustments on the same issue without sharing one mutable working copy.
• Use the jj operation log for undo, recovery, and audit when AI changes diverge or go out of scope.
• Prefer jj for local mutating history operations if enabled; avoid mixing arbitrary mutating git commands with jj in the same workspace.
• If colocated workspaces are used, keep git mostly read-only except for explicit remote operations such as fetch/push handled by the workflow.
• Do not require jj in CI or for non-engineer participants. jj is an internal accelerator, not the product front door.

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.
• references/issue-template-standard.md: standard issue templates for bug, enhancement, and feature.
• references/plan-template.md: default plan structure and status machine for MajorAgent/SubAgent/TestAgent handoff.
• references/jj-default-usage.md: default jj installation strategy, verification, and scenario-based usage guidance.

Operational Constraints

• Never start coding from an unselected issue unless the user explicitly enables autonomous queue mode.
• Never skip plan creation for a delivery issue.
• Never modify files outside the planned scope without an explicit plan update or user approval.
• Never claim success without verification evidence.
• Never introduce new dependencies or deprecated libraries without compatibility review.
• 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.