📦 @goodandready/dsh-gitea
Enterprise Gitea & Forgejo Integration Suite for DeepSeek Harness
🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明
⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it.
🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
|
🌟 What's New in v0.7.6
- One-Click Auto-Updater: Check npm and upgrade directly in the DSH settings card.
- Composition Services: Exposes
dshGitea (task provisioning) and giteaEvents (safe telemetry bridge for @goodandready/dsh-pulse).
- Security & Hygiene: Loopback and origin-hardened HTTP write guards (
lib/http-guard.js), sanitized GitHub release export pipeline (publish.sh).
- Performance & Caching: Cache invalidation on git mutations and modularized
lib/tool-defs.js.
🌟 What's New in v0.7.5
- Canonical English Server & Agent Tool Outputs: All tool responses, verification details, and error messages conform strictly to
dsh-plugin-authoring canonical English standard.
- Clean Package Boundaries: Standalone issue form templates are safely organized in
assets/issue-templates/; internal development specs (docs/superpowers/, .gitea/) are strictly excluded from npm packages.
- Automated Compliance Quality Gate: Permanent test coverage enforcing 0 Cyrillic characters across
lib/ and strict package file boundary audits.
⚡ Overview & Problem Solved
When autonomous AI coding agents perform complex multi-step development in DeepSeek Harness, they require seamless access to issue trackers, pull request review workflows, branch creation, and isolated workspace worktrees without risking repository corruption or leaking credentials into chat logs.
@goodandready/dsh-gitea bridges DeepSeek Harness to self-hosted Gitea and Forgejo instances. It equips agents with a complete suite of 20+ structured tools, registers a live Git Status Chip directly in the Web UI chat header, and enforces safety rails (confirm: true merge guards and dedicated write wrappers).
🏗️ Architecture
graph LR
subgraph DSH ["DeepSeek Harness"]
UI["Web UI Chat Header<br/>(Git Status Chip)"]
Agent["Autonomous Agent<br/>(20+ Gitea Tools)"]
Creds["Credentials Store<br/>(GITEA_TOKEN Ref)"]
end
subgraph Plugin ["dsh-gitea Plugin"]
ChipPoller["/git-status API<br/>Branch & Diff Inspector"]
Client["GiteaClient<br/>(REST API v1)"]
WorktreeMgr["Worktree Manager<br/>(Isolated Task Trees)"]
end
subgraph Server ["Self-Hosted VCS"]
Gitea["Gitea / Forgejo Server<br/>(Issues, PRs, Labels, Milestones)"]
GitRepo["Git Repository<br/>(Worktrees & Remotes)"]
end
UI -->|Polls Status| ChipPoller
ChipPoller -->|Reads Status| GitRepo
Agent -->|Executes Tools| Client
Agent -->|Manages Branches| WorktreeMgr
WorktreeMgr -->|git worktree| GitRepo
Client -->|Authenticated REST| Gitea
Creds -.->|Resolves In-Memory| Client
✨ Full Feature Breakdown
1. 20+ Agent Tools Suite
All tools infer owner and repo automatically from the active workspace's git remote get-url origin when omitted by the agent.
| Tool Name | Scope | Description | Safety Requirements |
|---|
gitea_labels | Labels | Consolidated label facade: list, create, delete, set | - |
gitea_milestones | Milestones | Consolidated milestone facade: list, create, update, delete | ⚠️ Delete requires confirm: true |
gitea_releases | Releases | Consolidated release facade: list, create, update, delete, plan, notes | ⚠️ Delete requires confirm: true |
gitea_ci | CI / Actions | Consolidated CI facade: status, jobs, rerun, explain | ⚠️ Rerun requires confirm: true |
gitea_branches | Branches | Consolidated branch facade: list, create, delete | ⚠️ Delete requires confirm: true |
gitea_tags | Tags | Consolidated tag facade: list, create, delete | ⚠️ Delete requires confirm: true |
gitea_webhooks | Webhooks | Consolidated webhook facade: list, create, delete | ⚠️ Delete requires confirm: true |
gitea_org | Org & Teams |
(Note: Legacy individual tool names such as gitea_label_list, gitea_release_now, gitea_ci_explain, etc. remain 100% supported via automatic backward compatibility mapping).
2. Per-branch PR templates
When creating a PR via issue-flow without an explicit body, the plugin fills a template by branch type: feat/, fix/, docs/, chore/, refactor/.
3. Live Git Status Chip & Topological Commit Graph
The client component injects a real-time Git Status Chip into the DSH Web UI chat header:
- Active Repository & Branch: Displays current branch name (e.g.,
feature/issue-42-auth).
- Tree Cleanliness: Color-coded badges indicating clean vs dirty working trees and modified files count.
- Ahead/Behind Sync Badges: Real-time sync indicator (
↑ahead, ↓behind) relative to upstream or origin/<branch>.
- Topological Commit Graph Modal: Monospace branch/merge lane visualization (
●, ◆, │), commit links to Gitea Web UI, branch and tag badges, and live Gitea Actions CI statuses (CI ✓, CI ✗, CI ●).
- Cross-Tab Synchronization: Efficient multi-tab coordination using
navigator.locks leader election and BroadcastChannel, eliminating duplicate network polling.
- Uncommitted Diff Inspector: 1-click panel showing recent commits and uncommitted diff.
3. Worktree Isolation & Agent Safety Rails
To allow autonomous agents to work on multiple issues without touching the primary branch:
- Non-destructive Worktrees: Creates worktree paths under
.worktrees/issue-<id>/ or custom directories.
- Confirm Guard Matrix: Destructive operations like
gitea_pr_merge and gitea_worktree_remove strictly require explicit boolean confirm: true. Unconfirmed tool calls are automatically rejected.
- Git Wrapper Enforcement: Write operations can be routed through a dedicated wrapper (
gitWrapper, e.g., git-deepseek-harness) to enforce agent author signatures.
4. Gitea Issue Templates Pack
Includes standardized Gitea YAML issue templates under .gitea/ISSUE_TEMPLATE/:
| Template File | Purpose | Recommended Starter Labels |
|---|
bug.yaml | Bug report | type/bug, status/ready |
feature.yaml | Feature proposal | type/feature, status/ready |
security.yaml | Security vulnerability | type/security, priority/high, scope/security |
research.yaml | Architectural research / spike | type/research, status/ready |
tech-debt.yaml | Technical debt & refactoring | type/tech-debt, status/ready |
incident.yaml | Production incident report | type/incident, priority/critical |
config-change.yaml | Infrastructure & config change | type/refactor, scope/settings, status/ready |
📦 Installation
Install via DeepSeek Harness CLI:
dsh plugin --profile web add @goodandready/dsh-gitea
Restart DSH Web UI and perform a hard-refresh (Ctrl+F5 or Cmd+Shift+R).
⚙️ Configuration
Navigate to Settings -> Plugins -> Gitea:
# config.yaml
dsh-gitea:
baseUrl: "https://gitea.yourcompany.com"
tokenEnv: "GITEA_TOKEN"
gitWrapper: ""
timeoutMs: 15000
Settings Reference Table
The plugin settings card in Settings -> Plugins -> Gitea organizes all 17 schema options into intuitive Core and Advanced sections:
| Key | Type | Default | Section | Description |
|---|
baseUrl | string | "" | Core | Base URL of your Gitea or Forgejo instance (e.g. https://gitea.example.com) |
tokenEnv | string | "GITEA_TOKEN" | Core | Name of the DSH Credential containing the personal access token |
defaultOwner | string | "" | Core | Default organization or user when tool calls omit owner |
defaultRepo | string | "" | Core | Default repository name when tool calls omit repo |
gitWrapper | string | "" | Advanced (Git) | Optional executable wrapper for write operations (e.g. git-dsh) |
dodReminder | boolean | false | Advanced (Git) | Definition of Done reminder if a tool changes git files without referencing an issue/PR |
forceHttpsUrls | boolean | false | Advanced (Git) | Rewrite http:// links to https:// behind an HTTPS reverse proxy |
timeoutMs | number | 30000 | Advanced (Git) |
[!IMPORTANT]
Never put the raw API token in the tokenEnv field. Store the token securely in DSH Credentials and enter only its reference key name.
🔒 HTTPS and mixed content
When DSH is served over HTTPS, embedded Gitea pages must also be HTTPS or the
browser blocks them (mixed content). Requirements:
- Configure Gitea behind HTTPS (or a reverse proxy) and set Instance URL to
the HTTPS endpoint — then generated links are already HTTPS.
- If Gitea only answers HTTP while DSH is HTTPS, the Settings card shows a
warning. Optionally enable
forceHttpsUrls to rewrite http:// links to
https:// in tool results when Gitea sits behind an HTTPS reverse proxy that
accepts both schemes.
- Never disable the browser's mixed-content protections.
🛠️ Reliability, Webhooks & Multi-Platform Support
Added in v0.4.3:
- Webhook Delivery:
gitea_digest_delivery and push notification dispatchers use fully-formed HTTP POST JSON requests with standard headers, ensuring delivery to Slack, Discord, Telegram, or custom webhook endpoints.
- Cross-Platform Path Resolution: Seamless operation across both POSIX (Linux/macOS) and Windows file systems, normalizing path separators and handling drive letters transparently.
- Accurate Merge Analytics:
gitea_repo_analytics accurately detects merged pull requests matching Gitea's REST API merged: true specifications.
- Branch & Path Policy Checking:
gitea_pr_policy reliably parses requiredChecks rules alongside protected branch paths from YAML configuration files.
- Autonomous Tool Routing: Non-repository tools (
gitea_repo_create_org, gitea_repo_bootstrap, gitea_digest_delivery) execute cleanly without requiring an active local Git repository origin.
🧪 Testing & Verification
Run the comprehensive unit and integration test suite:
npm test
📄 License
MIT © GooDAnDReaDY
Public composition service
The server half exposes an optional dshGitea composition service when the host
supports Cordis service providers. Its createIssue({ owner, repo, title, body,
labels, externalRef }) method reuses the configured Gitea URL and credential,
validates repository segments, and returns a normalized issue object with
ok, number, and url. It never starts an agent session.
externalRef is copied into a hidden body marker so cooperating plugins can
trace the issue they requested. Missing configuration and API failures are
returned as structured errors; consumers must fail closed. The canonical
consumer contract for task provisioning is
dsh-drives.task-provision.v1.
Gitea Events Service (giteaEvents)
dsh-gitea exposes a producer-owned giteaEvents composition service for telemetry consumers (such as @goodandready/dsh-pulse):
const stop = ctx.giteaEvents.subscribe((event) => {
// event: { id, event, action, at, giteaContext: { owner, repo, issue, pull, project, ref } }
})
- Allowlisted safe metadata: Only public identifier fields (
id, event, action, at, owner, repo, issue, pull, ref) are emitted.
- Zero secrets: Tokens, webhook secrets, request headers, raw payloads, and issue/PR comment bodies are never exposed.
- Fault isolation: Subscriber errors are completely isolated and never impact the webhook HTTP response or other subscribers.
Plugin Auto-Updater
The settings card provides a one-click auto-updater powered by /api/dsh-gitea/update:
- Status check: Checks npm registry for updates without SSH or command-line access.
- Secure installation: Accepts write requests only from local loopback origins with
x-dsh-plugin-update: 1.
- Safe dependencies: Honors npm release quarantine rules.
