95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
# git-forge-plugin
|
|
|
|
GitHub and Gitea/Forgejo integration for the DeepSeek Harness (DSH): **clone repositories into new workspaces** from the Web UI and give agents **`forge_*` tools** for repos, issues, pull requests and authenticated push. Tokens never leave the Host — they stay with the `gh` and `tea`/`tea-cli` CLIs.
|
|
|
|
## Features
|
|
|
|
### Web UI
|
|
- **Add workspace → Clone repository**: browse repos of every authorized account (or paste any git URL) and clone straight into a new workspace (default clone root: your home directory).
|
|
- **Add workspace → Open local folder**: folder browser (up/home/show hidden).
|
|
- **Settings → Plugins → Git Forge → Accounts**: list authorized accounts, check tokens, log out, and add accounts:
|
|
- GitHub via `gh`: browser device-code flow or a personal access token (classic, scopes `repo`, `read:org`, `gist`).
|
|
- Gitea / Forgejo via `tea-cli`: host + token, or user + password (tea creates a token).
|
|
|
|
### Agent tools
|
|
| Tool | Purpose |
|
|
| --- | --- |
|
|
| `forge_accounts` | List authorized GitHub (gh) and Gitea/Forgejo (tea-cli) accounts. |
|
|
| `forge_repos` | list / search / get / create / edit / fork / delete / branches / releases. |
|
|
| `forge_issues` | list / get / create / comment / edit / close / reopen. |
|
|
| `forge_pulls` | list / get / diff / create / comment / merge / close / reopen. |
|
|
| `forge_clone` | Clone with account credentials (private repos; SSH URLs switched to HTTPS+token when no SSH key). |
|
|
| `forge_push` | Push with the account token (sets upstream; `--force-with-lease` only on request). |
|
|
| `forge_api` | Raw authenticated REST call (GitHub `https://api.github.com`, Gitea/Forgejo `/api/v1`). |
|
|
|
|
Clone and push use a bundled git **credential helper** (`credential-helper.mjs`) passed via `git -c credential.helper=…`; it answers with the token of the gh/tea account whose host matches, and prints nothing otherwise (git falls through to your normal helpers). Your global git config is not modified.
|
|
|
|
## Requirements
|
|
|
|
- [`gh`](https://cli.github.com/) for GitHub accounts (optional).
|
|
- [`tea`](https://gitea.com/gitea/tea) (binary named `tea-cli` or `tea`) for Gitea/Forgejo accounts (optional).
|
|
- `git` and Node.js (already required by DSH).
|
|
|
|
At least one of `gh` / `tea` must be installed and logged in for the account features to do anything.
|
|
|
|
## Files
|
|
|
|
| File | Role |
|
|
| --- | --- |
|
|
| `index.js` | Host plugin: HTTP routes under `/git-forge/*` (accounts, repos, auth, ls, clone) and the `forge_*` tools. Injects `webServer`, `connection`, `tools`. |
|
|
| `forge.mjs` | Account discovery (gh + tea), REST access, git URL parsing, clone and push. |
|
|
| `auth.mjs` | Drives `gh auth login` / `tea login add` / logout for the settings panel. |
|
|
| `credential-helper.mjs` | git credential helper used by clone/push. |
|
|
| `client.js` | Web client: clone dialog, local folder picker, accounts settings panel. |
|
|
| `locale/*.json` | Plugin title/description (en, zh). |
|
|
| `cordis.patch.yml` | Bundle patch inserting the `git-forge` row. |
|
|
|
|
## Installation
|
|
|
|
Requirements: a working DeepSeek Harness (`dsh`) install with the **web** profile (or any profile that includes the Web UI).
|
|
|
|
### Option A — install from git (recommended)
|
|
|
|
```bash
|
|
dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git
|
|
```
|
|
|
|
You can also paste `git+https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git` into **Settings → Plugins → Install** in the Web UI, or ask the agent to install it with its `plugin_manager` tool (`install_bundle`).
|
|
|
|
The plugin manager adds `@local/git-forge` to `dependencies` and to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`.
|
|
|
|
### Option B — local checkout (for development)
|
|
|
|
```bash
|
|
git clone https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git ~/dsh-plugins/git-forge-plugin
|
|
dsh plugin --profile web add link:$HOME/dsh-plugins/git-forge-plugin
|
|
```
|
|
|
|
With a `link:` install, edits in the checkout are picked up directly (client changes reload on page refresh, Host changes after a DSH restart or HMR reload).
|
|
|
|
### Enable / verify
|
|
|
|
1. Make sure `@local/git-forge` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/web/package.json` (the installer does this; add it by hand if you edited `package.json` manually).
|
|
2. Restart DSH (`dsh web`) or reload the page.
|
|
3. Check **Settings → Plugins**: the `@local/git-forge` bundle should be enabled.
|
|
|
|
### Uninstall
|
|
|
|
```bash
|
|
dsh plugin --profile web remove @local/git-forge
|
|
```
|
|
|
|
### Updating
|
|
|
|
Re-run the `add` command from Option A (or `git pull` in your Option B checkout).
|
|
|
|
## Setup after install
|
|
|
|
1. Install and log in the CLIs on the Host machine (or use the settings panel to do it):
|
|
```bash
|
|
gh auth login # GitHub
|
|
tea login add --url https://gitea.example.com --token <TOKEN> # Gitea/Forgejo
|
|
```
|
|
2. Open **Settings → Plugins → Git Forge** and press **Check tokens** — each account should show *Token valid*.
|
|
3. In a chat, ask the agent e.g. *"list my repos"*; it will use `forge_repos`.
|