99 lines
5.5 KiB
Markdown
99 lines
5.5 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_fix_credentials` | Configure the local repository’s `.git/config` to use the bundled credential helper, replacing stale or broken local `credential.helper` entries. |
|
||
| `forge_api` | Raw authenticated REST call (GitHub `https://api.github.com`, Gitea/Forgejo `/api/v1`). |
|
||
|
||
`forge_fix_credentials` changes only the target repository’s local config; it does not modify global git configuration or expose tokens. Omit `path` to target the session working directory, or pass a repository path (including a nested path) to update that repository.
|
||
|
||
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) for Gitea/Forgejo accounts (optional). Both binary names are checked, `tea-cli`
|
||
first, then `tea`; whichever runs is used for logins, logout and the status line in settings.
|
||
- `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, push, and repository credential-helper configuration. |
|
||
| `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`.
|