GitHub 仓库管理与推送完整指南

GitHub 仓库管理与推送完整指南

本文记录了从零开始配置 Git 环境、创建 GitHub 仓库、推送代码、发布 Release 的完整流程。


目录

  1. 配置 Git 用户信息
  2. 生成 GitHub Personal Access Token
  3. 添加远程仓库
  4. 推送代码到 GitHub
  5. 通过 API 管理仓库
  6. 创建 Release
  7. 常见问题

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.namegit commit 的作者名Zhang San
user.emailgit commit 的邮箱zhangsan@example.com

注意: 这些信息会出现在每次 git commit 中,建议使用你的真实信息或 GitHub 用户名。


2. 生成 GitHub Personal Access Token

Token 用于 API 操作和 HTTPS 方式推送代码。

创建步骤

  1. 打开 https://github.com/settings/tokens
  2. 点击 “Generate new token (classic)”
  3. 填写 Note(备注):如 codegraph-dev
  4. 选择 Expiration(过期时间):建议 90 天
  5. 勾选权限(Scopes):
权限说明是否需要
repo完整仓库访问权限✅ 必须
workflow管理 GitHub Actions⚠️ 可选(推 workflow 文件需要)
admin:repo_hook管理仓库设置⚠️ 可选
  1. 点击 “Generate token”
  2. 立即复制 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 创建仓库

  1. 打开 https://github.com/new
  2. 填写仓库名称
  3. 选择 Public 或 Private
  4. 不要勾选 “Add a README file”
  5. 不要添加 .gitignore
  6. 点击 “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 网页(推荐)

  1. 打开 https://github.com/你的用户名/仓库名/releases/new?tag=v1.0.0
  2. 填写标题和描述
  3. 点击 “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