gitee-offline-ssh-repo

命令

Gitee 服务器 SSH 仓库管理

gitee-offline-ssh-repo

Gitee 服务器 SSH 仓库管理

前言

日常使用Gitee经常出现网页打不开、账号无法网页登录，但服务器SSH密钥已正常授权、ssh -T git@gitee.com连通成功的场景。原生git指令只能够对已存在的远程仓库实现代码拉取、推送，不能新建/重命名云端仓库；Gitee无官方apt格式CLI工具，最优方案：私人令牌Token + Curl调用Gitee开放API，全程终端操作，不用打开浏览器登录Gitee。

实测环境：FnOS Debian12、Intel N100 x86_64、用户名：meimolihan、Gitee令牌：你的Gitee私人令牌

一、环境前置操作

1. 校验Gitee SSH连通状态

ssh -T git@gitee.com

✅ 成功返回示例：

Hi meimolihan(@meimolihan)! You've successfully authenticated, but GITEE.COM does not provide shell access.

重要说明：SSH鉴权只负责git代码推拉，创建/修改云端仓库必须依靠Gitee私人令牌Token调用API。

二、前期准备：账号信息

Gitee用户名：meimolihan
Gitee私人令牌：你的Gitee私人令牌

令牌权限仅需勾选：projects仓库权限即可完成新建、改名、私有化切换。

三、Curl API创建远程仓库【重要修正：Gitee新版API废弃private字段，使用visibility控制公私】

❌ 旧写法：private:false / private:true 失效，部分场景依旧生成私有仓库 ✅ 新标准：visibility:"public"=公开仓库；visibility:"private"=私有仓库

3.1 创建【公开仓库】cmdbox

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/user/repos \
-d '{
"name":"cmdbox",
"visibility":"public",
"auto_init":true,
"description":"cmdbox工具箱主仓库"
}'

3.2 创建【私有仓库】cmdbox

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/user/repos \
-d '{
"name":"cmdbox",
"visibility":"private",
"auto_init":true,
"description":"cmdbox工具箱主仓库"
}'

3.3 示例：创建公开仓库 cmdbox-main

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/user/repos \
-d '{
"name":"cmdbox-main",
"visibility":"public",
"auto_init":true,
"description":"cmdbox主线版本仓库"
}'

参数	作用
name	远程仓库名称
visibility:"public"	开源公开仓库（新版标准）
visibility:"private"	私有私密仓库（新版标准）
auto_init:true	自动初始化生成README.md
description	仓库简介备注

四、执行结果判断

✅ 返回201状态+JSON数据：云端仓库创建成功
❌ 401 Unauthorized：令牌错误、过期、权限缺失
❌ 422 Unprocessable Entity：同名仓库已存在、参数错误

五、已存在私有仓库一键转为公开（实操修正项）

已创建仓库如果是私有，不用删库重建，直接PATCH修改可见性：

# meimolihan/cmdbox 私有转公开
curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/repos/meimolihan/cmdbox \
-d '{"visibility":"public"}'

六、SSH克隆仓库到本地

仓库云端创建完毕，使用SSH免密克隆到本地，无需账号密码：

# 克隆cmdbox仓库
git clone git@gitee.com:meimolihan/cmdbox.git
# 进入项目目录
cd cmdbox

七、本地代码提交推送测试

# 新建测试文件
echo "Hello CmdBox Gitee" > test.md
# 加入暂存区
git add .
# 提交本地记录
git commit -m "init: first commit for gitee cmdbox"
# 推送至远程master分支（Gitee默认master，GitHub默认main）
git push origin master

八、仓库重命名操作（云端改名+本地配置同步）

8.1 API修改云端仓库名称（例：CmdBox → cmdbox）

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/repos/meimolihan/CmdBox \
-d '{"name":"cmdbox"}'

返回200即云端改名成功

8.2 修改本地git远程地址

git remote set-url origin git@gitee.com:meimolihan/cmdbox.git
# 校验远程配置
git remote -v

8.3 （可选）本地文件夹同步重命名

cd ../
mv CmdBox cmdbox
cd cmdbox

8.4 查看当前仓库名称

# 1.本地查看已绑定远程仓库名
git remote -v
# 2.API查询云端真实仓库名称
curl -H "Authorization: token 你的Gitee私人令牌" https://gitee.com/api/v5/repos/meimolihan/cmdbox

返回JSON中name字段为云端正式仓库名称。

九、通用新建仓库模板

只修改name和description即可一键新建任意公开仓库：

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: token 你的Gitee私人令牌" \
https://gitee.com/api/v5/user/repos \
-d '{
"name":"自定义仓库名",
"visibility":"public",
"auto_init":true,
"description":"自定义仓库备注"
}'

十、总结

Gitee SSH密钥仅用于已有仓库的代码拉取推送，无法创建、重命名云端仓库，必须使用私人令牌调用API；
⚠️ 关键踩坑：Gitee新版API取消private布尔参数，必须用visibility:"public/private"控制仓库公私，旧private:false写法失效；
Gitee私人令牌只需勾选projects仓库权限，无强制组织权限限制，配置比GitHub Token简单；
网页无法登录场景，全程依靠curl+token完成新建、改名、公私切换、克隆、推送全套仓库管理；
GitHub默认分支main，Gitee默认分支master，提交推送注意分支名称区别。