众元AI学习空间

04_GitHub远端仓库与Actions首次运行手册

8分钟阅读

GitHub 远端仓库与 Actions 首次运行手册

使用时间：W02-D02 完成账号、远端、首次 push 和 clone；W03-D04 再完成 Actions 首次运行。
前置：已完成本地 Git 安装、身份配置和至少一次本地 commit。
课堂默认：新建 Private 仓库；不上传真实简历、真实 Key、个人敏感数据或教师参考代码。

1. 由学生本人创建或检查 GitHub 账号

  1. 打开 GitHub 注册页。
  2. 使用学生本人可长期访问的邮箱创建个人账号，或按学校提供的组织账号流程登录。
  3. 完成邮箱验证。未验证邮箱会限制创建仓库等基础功能。
  4. 建议按 GitHub 官方提示配置 2FA，并把恢复码保存在学生自己的安全位置；教师不收取恢复码、密码、验证码或 Passkey。
  5. 登录后确认浏览器最终显示自己的 GitHub 首页和头像，而不是只看到一次“成功”提示。

账号注册、邮箱验证、验证码和 2FA 都是学生的人审步骤。课堂可等待和排错，但不代操作。

2. 创建一个与本地项目对应的空仓库

以 W03 项目 W03-commerce-web 为例：

  1. 登录 GitHub，点击右上角 + → New repository。
  2. Owner 选择自己的账号或教师指定的课堂组织。
  3. Repository name 填本人/团队冻结的 W03 仓库名，例如 w03-commerce-web-team-a。
  4. Visibility 选择 Private。
  5. 因为本地已经有 README、.gitignore 和 commit，本次 不要 勾选初始化 README、.gitignore 或 License，避免首次 push 前产生两套不相关历史。
  6. 点击 Create repository。
  7. 保留创建完成页面，复制 HTTPS 地址，格式类似：
https://github.com/你的账号/w03-commerce-web-team-a.git

3. 推送前先做密钥和范围检查

在本地项目根目录执行：

git rev-parse --show-toplevel
git status
git log --oneline -3
git remote -v

检查：

  • 仓库根目录是本周项目，不是整个课程目录或磁盘。
  • .venv/、.env、artifacts/ 中的敏感证据和真实数据已按课程规则忽略。
  • 暂存和提交中没有 API Key、真实简历、访问令牌、浏览器下载文件或教师参考代码。
  • git remote -v 若已有 origin，先读清地址，不要直接重复添加或删除。

可使用：

git diff --staged
git grep -n -I -E "(API_KEY|SECRET|TOKEN|PASSWORD)" HEAD

第二条只是一项辅助扫描，不能证明仓库绝对没有秘密；仍要人工看 diff 和文件范围。

4. 添加远端并完成第一次 push

没有 origin 时：

git remote add origin https://github.com/你的账号/w03-commerce-web-team-a.git
git remote -v
git branch -M main
git push -u origin main

首次 HTTPS push 时，Git Credential Manager 通常会打开浏览器：

  1. 检查浏览器域名确实是 GitHub。
  2. 由学生本人登录并授权。
  3. 回到终端等待 push 完成。
  4. 刷新 GitHub 仓库主页，确认文件和最新 commit 真正出现。

不要在终端的“Password”提示中输入 GitHub 账号密码。若组织策略没有启用浏览器授权，按组织批准方式使用 Personal Access Token；Token 只由学生本人创建和保管，不粘贴到课件、群聊或截图。

已有错误 origin 时，先查看：

git remote -v

确认新地址后再修改：

git remote set-url origin https://github.com/你的账号/w03-commerce-web-team-a.git
git remote -v

5. 放入课程 CI 工作流

GitHub 只会识别 .github/workflows/ 下扩展名为 .yml 或 .yaml 的工作流。

  1. 在本地项目创建 .github/workflows/ci.yml。
  2. 使用 W03-D04 课堂课件提供的 Python CI 完整内容，不临时复制网上未知 Action。
  3. 本地审查文件路径、Python 版本、requirements.txt 路径和测试工作目录。
  4. 提交并推送：
git add .github/workflows/ci.yml
git diff --staged
git commit -m "ci: run backend tests"
git push
  1. 在 GitHub 仓库打开 Actions。
  2. 点击本次 workflow run，再点击具体 job，展开每一步日志。
  3. 记录 run URL、commit SHA、Python 版本、依赖安装和 pytest 结果。

绿色勾只说明这一份 workflow 对这一份 commit 运行成功；必须确认页面上的 commit SHA 与刚推送的一致。

6. Actions 没运行或失败怎么办

看不到 Actions 标签

确认：

  • 浏览器打开的是正确仓库；
  • 当前账号有该仓库权限；
  • 仓库 Settings → Actions 没有被组织策略禁用。

组织策略问题由教师/管理员处理，学生不要尝试绕过。

工作流没有触发

检查：

git status
git log --oneline -3
git ls-files .github/workflows
git remote -v

然后核对 workflow 的 on: 是否包含当前 push/分支。文件只存在本地但没 commit/push，云端不会运行。

依赖安装失败

先读日志中第一条真实错误，再依次检查：工作目录、Python 版本、依赖文件路径、锁定版本、网络/缓存。不要把“本地测试通过”当成云端依赖已经正确安装。

pytest 找不到项目模块

对照仓库根目录与 workflow 的 working-directory。CI 从仓库根目录开始，不知道某台教师电脑的绝对路径。

push 被拒绝

  • repository not found：核对 owner、仓库名、可见性和登录账号。
  • authentication failed：清理错误账号的凭据要谨慎，先确认当前浏览器身份和 remote URL；由学生本人重新授权。
  • non-fast-forward：远端可能被初始化或已有提交。先停下并比较两边历史，不直接 force push。

7. 课堂验收单

GitHub 账号邮箱已验证：是 / 否
仓库可见性：Private / 由教师批准的其他设置
本地仓库根目录：
origin 地址（不得含 Token）：
首次 push：成功 / 失败
GitHub 页面最新 commit SHA：
Actions run URL：
Actions 对应 commit SHA：
CI 结果：成功 / 失败
失败日志第一条真实错误：

官方资料：创建 GitHub 账号、管理远端仓库、GitHub Actions 快速入门。

反向链接