# Gitea：SSH / GPG 配置与验证

依据官方文档与 Gitea UI 源码整理（用户侧）。管理员侧签名见文末链接。

- 官方：[GPG/SSH Commit Signatures](https://docs.gitea.com/administration/signing/)
- 密钥页：`https://<你的Gitea>/user/settings/keys`
- 信任模型（管理员）：`[repository.signing] DEFAULT_TRUST_MODEL`（`collaborator` / `committer` / `collaboratorcommitter`）

## 网页图标含义（官方）

| 图标 | 含义 |
| --- | --- |
| 灰色开锁 | **数据库中找不到**可用于校验的密钥（中文常见：「找不到此签名对应的密钥」） |
| 红色开锁 | 声称已签名，但密钥有问题 / 不可信 |
| 已验证锁 | 签名可被 Gitea 用库中**已验证**密钥校验，且符合仓库信任模型 |

**只「添加」公钥不够。** SSH 用于提交签名识别、以及 GPG 显示已验证，通常都要求在设置页完成 **验证**（证明持有对应私钥）。见 [go-gitea/gitea#20597](https://github.com/go-gitea/gitea/issues/20597)。

## 远程 URL

```
https://git.example.com/owner/repo.git
https://git.example.com:3000/owner/repo.git
git@git.example.com:owner/repo.git
ssh://git@git.example.com:2222/owner/repo.git
```

HTTPS 非默认端口会写入 GCM `host=name:port`。详见 Skill 脚本 `Parse-GitRemoteUrl`。

## 一、SSH 密钥（推送 + 可选 SSH 签名）

### 1. 本机生成 / 复用

Skill：`ensure-ssh.ps1`（默认 `~/.ssh/id_ed25519`）。

### 2. 添加到 Gitea

1. **设置** → **SSH / GPG 密钥** → **增加密钥**
2. 粘贴**公钥**（`.pub` 一整行）
3. 保存

### 3. 验证 SSH 密钥（必须，否则 SSH 签名提交会「找不到密钥」）

1. 在该密钥旁点 **验证**
2. 复制页面令牌（每次不同，勿写入仓库）
3. 官方 UI 给出的命令形态（见 `keys_ssh.tmpl`）：

```bash
echo -n 'TOKEN' | ssh-keygen -Y sign -n gitea -f /path/to/id_ed25519
```

Windows 推荐用 Skill 脚本（避免 PowerShell/`echo` 编码问题）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/verify-ssh-challenge.ps1" `
  -Token "TOKEN_FROM_PAGE" `
  -KeyPath "$env:USERPROFILE\.ssh\id_ed25519"
```

4. 将输出的 `-----BEGIN SSH SIGNATURE-----` … 整段贴回页面 → **验证**
5. 成功后应出现「已验证」标记

也可用公钥路径（agent 持有私钥时）：`-KeyPath` 指向 `.pub` 亦可（OpenSSH 会经 agent 签名）。

### 4. 测试推送认证（与「签名验证」不同）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/test-ssh.ps1" -RemoteUrl "<SSH仓库URL>"
```

## 二、GPG 密钥（本 Skill 默认的提交签名方式）

### 1. 本机生成 / 复用

Skill：`ensure-gpg.ps1`。导出公钥：

```powershell
& "$env:ProgramFiles\Git\usr\bin\gpg.exe" --armor --export KEY_ID
```

### 2. 添加到 Gitea

1. **设置** → **SSH / GPG 密钥** → GPG 区 **增加密钥**
2. 粘贴 ASCII 公钥（`BEGIN PGP PUBLIC KEY BLOCK`）
3. 保存；确认 **匹配身份** 含 Gitea 账号已验证邮箱（如 `travelxiao@qq.com`）

### 3. 验证 GPG 密钥（必须）

官方 UI 命令形态（见 `keys_gpg.tmpl`）：

```bash
echo "TOKEN" | gpg -a --default-key KEY_ID --detach-sig
```

注意：这里是 **带换行** 的 `echo "TOKEN"`（与 SSH 的 `echo -n` 不同）。

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/verify-gpg-challenge.ps1" `
  -Token "TOKEN_FROM_PAGE" `
  -KeyId "5996DA789B43D451"
```

将 `-----BEGIN PGP SIGNATURE-----` … 贴回 → **验证**。

### 4. 本地 Git 使用同一把 GPG 钥签名

```powershell
git config user.signingkey KEY_ID          # 仓库 local；或按需 --global
git config commit.gpgsign true
# 使用 GPG 时不要设置 gpg.format=ssh
git config --unset gpg.format              # 若曾设为 ssh
```

Skill 的 `prepare-commit.ps1` / Init 流程会设置 local `user.signingkey` 与 `commit.gpgsign`。

## 三、排错：「找不到此签名对应的密钥」

按官方说明，灰色开锁 = Gitea **库中没有**可用来校验该签名的密钥。常见原因：

1. 公钥已添加但 **未验证** → 先完成上一节验证
2. 本地 `user.signingkey` / `gpg.format` 与网页上的密钥不是同一把  
   - GPG：`gpg.format` 未设或为 openpgp，`signingkey` = 网页 Key ID  
   - SSH 签名：`gpg.format=ssh`，且对应 SSH 密钥已在 Gitea **验证**
3. 提交作者邮箱不在 Gitea 账号邮箱列表 / 与 GPG uid 不一致 → 在 Gitea 添加并验证该邮箱
4. 仓库 **信任模型**（`DEFAULT_TRUST_MODEL`）导致虽能识别密钥但不显示为可信（管理员配置；默认常为 `collaborator`）
5. 验证成功后请 **硬刷新**（Ctrl+F5）；**旧提交**可能仍显示开锁，新提交才变绿

检查本机：

```powershell
git config --get user.signingkey
git config --get gpg.format
git config --get user.email
git log -1 --show-signature
```

## 四、Token（HTTPS 推送）

与密钥验证令牌不同：这是 **访问令牌**（设置 → 应用）。

- 用户名：Gitea 登录名（档案 `gitUsername`）
- 密码：访问令牌  
- 本机：`store-token.ps1`（DPAPI），禁止发到对话

## 五、Agent 流程（密钥验证 — 主动询问）

HTTPS **访问令牌**仍禁止进对话。Gitea 页面上的 **验证挑战令牌**（一次性）允许 Agent 主动索取。

1. `ensure-ssh.ps1` / `ensure-gpg.ps1` → 用户把公钥加到 Gitea  
2. Agent **主动询问**：
   - GPG 验证页令牌
   - SSH 验证页令牌（与 GPG 不同）
3. 收到后执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/verify-gitea-keys.ps1" `
  -GpgToken "<gpg>" -SshToken "<ssh>" -KeyId "<key_id>"
```

4. 把生成的签名块发给用户，指导贴回 Gitea → **验证**  
5. 用户确认「已验证」后，本地 `commit.gpgsign` + `user.signingkey`  
6. `test-ssh.ps1` 测推送通道  

缺令牌时脚本输出 `need_token` / `waiting_for_tokens`，Agent 继续追问，不要跳过。

## 六、管理员参考（非本机 Skill 必做）

服务器可用 `[repository.signing]` 让 Gitea 自己签 merge 等提交；见官方文档。用户侧密钥验证不依赖该项，但信任模型会影响「已验证」展示。

官方文档：

- https://docs.gitea.com/administration/signing/
- https://docs.gitea.com/administration/config-cheat-sheet/（`DEFAULT_TRUST_MODEL` 等）