GitHub 仓库管理与推送完整指南
本文记录了从零开始配置 Git 环境、创建 GitHub 仓库、推送代码、发布 Release 的完整流程。
目录
- 配置 Git 用户信息
- 生成 GitHub Personal Access Token
- 添加远程仓库
- 推送代码到 GitHub
- 通过 API 管理仓库
- 创建 Release
- 常见问题
1. 配置 Git 用户信息
1
2
3
4
5
6
7
8
| # 设置全局用户名(用于提交记录)
git config --global user.name "你的用户名"
# 设置全局邮箱(用于提交记录)
git config --global user.email "你的邮箱@example.com"
# 验证配置
git config --global --list | grep user
|
配置说明
| 配置项 | 用途 | 示例 |
|---|
user.name | git commit 的作者名 | Zhang San |
user.email | git commit 的邮箱 | zhangsan@example.com |
注意: 这些信息会出现在每次 git commit 中,建议使用你的真实信息或 GitHub 用户名。
2. 生成 GitHub Personal Access Token
Token 用于 API 操作和 HTTPS 方式推送代码。
创建步骤
- 打开 https://github.com/settings/tokens
- 点击 “Generate new token (classic)”
- 填写 Note(备注):如
codegraph-dev - 选择 Expiration(过期时间):建议 90 天
- 勾选权限(Scopes):
| 权限 | 说明 | 是否需要 |
|---|
repo | 完整仓库访问权限 | ✅ 必须 |
workflow | 管理 GitHub Actions | ⚠️ 可选(推 workflow 文件需要) |
admin:repo_hook | 管理仓库设置 | ⚠️ 可选 |
- 点击 “Generate token”
- 立即复制 Token(只显示一次!)
Token 使用方式
1
2
3
4
5
| # 方式 1:设置环境变量(推荐,安全)
export GITHUB_TOKEN="ghp_你的token"
# 方式 2:嵌入远程仓库 URL(临时使用)
git remote set-url origin https://<用户名>:<TOKEN>@github.com/<用户名>/<仓库名>.git
|
⚠️ 安全提示:
- Token 不要提交到代码仓库
- 不要在公共场合分享 Token
- 使用环境变量方式更安全
- 定期轮换 Token
3. 添加远程仓库
3.1 在 GitHub 创建仓库
- 打开 https://github.com/new
- 填写仓库名称
- 选择 Public 或 Private
- 不要勾选 “Add a README file”
- 不要添加 .gitignore
- 点击 “Create repository”
3.2 添加远程仓库
1
2
3
4
5
| # 添加你自己的仓库作为远程地址
git remote add myrepo https://github.com/你的用户名/仓库名.git
# 查看所有远程仓库
git remote -v
|
3.3 配置 Token 认证
1
2
3
4
5
| # 设置环境变量
export GITHUB_TOKEN="ghp_你的token"
# 临时使用 Token 推送(不修改 remote URL)
git push https://$GITHUB_TOKEN@github.com/你的用户名/仓库名.git 分支名
|
4. 推送代码到 GitHub
4.1 基本流程
1
2
3
4
5
6
7
8
9
10
11
| # 1. 检查当前状态
git status
# 2. 添加所有更改
git add -A
# 3. 提交更改
git commit -m "feat: 你的提交信息"
# 4. 推送到你自己的仓库
git push myrepo 分支名
|
4.2 排除特定文件推送
如果某些文件(如 CI/CD 配置)因权限问题无法推送:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| # 创建一个不包含这些文件的新分支
git checkout -b push-branch
# 移除缓存中的文件
git rm -r --cached .github/workflows/
# 提交更改
git commit -m "chore: remove workflow files for push"
# 推送新分支
git push myrepo push-branch
# 切换回原分支
git checkout 原分支名
# 删除临时分支(可选)
git branch -D push-branch
|
5. 通过 API 管理仓库
5.1 更新仓库描述
1
2
3
4
5
| curl -X PATCH \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/你的用户名/仓库名 \
-d '{"description": "仓库描述"}'
|
5.2 更新仓库主题(Topics)
1
2
3
4
5
| curl -X PUT \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/你的用户名/仓库名/topics \
-d '{"names": ["topic1", "topic2", "topic3"]}'
|
5.3 查询仓库信息
1
2
3
4
| curl -s \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/你的用户名/仓库名 | python3 -m json.tool
|
6. 创建 Release
6.1 创建标签
1
2
3
4
5
6
7
8
9
10
| # 方式 1:通过 Git 创建并推送
git tag -a v1.0.0 -m "Release version 1.0.0"
git push myrepo v1.0.0
# 方式 2:通过 API 创建
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/你的用户名/仓库名/git/refs \
-d '{"ref": "refs/tags/v1.0.0", "sha": "提交SHA"}'
|
6.2 创建 Release
方式 1:通过 GitHub 网页(推荐)
- 打开 https://github.com/你的用户名/仓库名/releases/new?tag=v1.0.0
- 填写标题和描述
- 点击 “Publish release”
方式 2:通过脚本
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| #!/bin/bash
set -e
GITHUB_TOKEN="ghp_你的token"
REPO="你的用户名/仓库名"
# 创建 JSON 文件
cat > /tmp/release.json << 'ENDJSON'
{
"tag_name": "v1.0.0",
"target_commitish": "main",
"name": "v1.0.0 - 版本名称",
"body": "## 更新内容\n\n- 功能 1\n- 功能 2\n\n## 修复内容\n\n- Bug 修复 1"
}
ENDJSON
# 发送请求
curl -s -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/$REPO/releases \
-d @/tmp/release.json | python3 -c "import sys, json; d=json.load(sys.stdin); print('Release URL:', d.get('html_url', '创建失败'))"
rm -f /tmp/release.json
|
7. 常见问题
Q1: 推送时提示 “Permission denied”
原因: Token 权限不足或未正确配置
解决:
1
2
3
4
5
| # 重新设置 Token
export GITHUB_TOKEN="ghp_你的token"
# 使用 Token 推送
git push https://$GITHUB_TOKEN@github.com/用户名/仓库名.git 分支名
|
Q2: 推送 Workflow 文件失败
原因: Token 缺少 workflow 权限
解决:
1
2
3
4
5
6
7
| # 方案 1:更新 Token 权限(添加 workflow scope)
# 方案 2:排除 workflow 文件推送
git checkout -b push-branch
git rm -r --cached .github/workflows/
git commit -m "chore: remove workflow files"
git push myrepo push-branch
|
Q3: API 调用返回 404
原因: 仓库不存在或 Token 无访问权限
解决:
1
2
3
| # 确认仓库存在
curl -s -H "Authorization: token $GITHUB_TOKEN" \
https://api.github.com/repos/用户名/仓库名 | grep -E '"full_name"|"message"'
|
附录:常用 Git 命令速查
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| # 状态查看
git status # 查看工作区状态
git log --oneline -5 # 查看最近 5 条提交
git branch -a # 查看所有分支
# 分支操作
git checkout -b 新分支名 # 创建并切换分支
git checkout 分支名 # 切换分支
git branch -d 分支名 # 删除分支
# 提交操作
git add -A # 添加所有更改
git commit -m "提交信息" # 提交更改
git push remote 分支名 # 推送到远程
# 远程操作
git remote -v # 查看远程仓库
git remote add 名称 地址 # 添加远程仓库
git remote remove 名称 # 删除远程仓库
git fetch # 获取远程更新
git pull # 拉取并合并
|
文档版本:v1.0
更新日期:2026-05-29