GitHub | gitzw.com - GitHub 中文信息聚合网

入门

GitHub 入门

GitHub 不仅是一个代码托管平台，更是全球开发者的协作中心。通过本章的学习，你会掌握如何注册账号、设置个人资料，并学会上传项目到 GitHub。

准备工作

确保你已经在计算机上安装了 Git。可以通过在命令行输入 git --version 来检查是否已安装及查看版本号。如果未安装，请先下载并安装最新版本的 Git。

关于 GitHub 和 Git

GitHub 是一个基于 Git 的代码托管服务，提供了丰富的工具来管理和协作开发项目。
Git 是一个分布式版本控制系统，用于追踪代码变更的历史记录。

创建账户

访问 GitHub 官网并点击右上角的 "Sign up" 按钮。
输入用户名、电子邮件地址和密码完成注册。
根据提示完成邮箱验证。

设置个人资料

登录后，在页面右上角点击头像进入个人主页，选择 "Settings"。

Profile：可以填写个人信息如公司、博客、位置等。
Avatar：上传一张个性化的头像照片。

寻找灵感

浏览热门仓库或关注感兴趣的开源项目是个不错的选择：

访问 Explore 页面查看更多推荐项目。
通过搜索栏查找特定领域的项目。

上传项目

初始化本地仓库

假设你想将本地的一个文件夹变成一个 Git 仓库：

cd path/to/your/project-folder  # 切换到你的项目文件夹路径
git init                      # 初始化一个新的 Git 仓库

添加文件并提交更改

git add .                     # 添加当前目录下的所有文件到暂存区
git commit -m "Initial commit"  # 提交更改到本地仓库，并附带一条消息描述这次提交的内容

推送至 GitHub 远程仓库

登录 GitHub 后，在首页点击 "+" 图标选择 "New repository" 创建一个新的远程仓库。

复制生成的 git remote add origin ... 命令添加远程链接：

git remote add origin https://github.com/yourusername/repository-name.git

修改默认分支名称为 main（如果需要的话）：
```
git branch -M main          
```
最后推送本地代码到远程仓库：
```
git push -u origin main     
```

在 GitHub 上交流

利用 Issues 功能提出问题或建议改进；Pull Requests 可以用来发起对他人项目的贡献请求；Discussions 则适合进行非正式的讨论和分享想法。

支持的浏览器和移动应用

确保使用最新版本的支持浏览器访问 GitHub 或者下载 GitHub 移动版应用方便随时随地查看和管理项目。

实战案例：创建并共享一个小网站项目

在本地创建一个新的文件夹命名为 my-first-site，并在其中编写 HTML/CSS 文件构建简单的网页布局。
使用上述方法初始化 Git 仓库并将所有相关文件添加到暂存区并提交更改。
登录 GitHub 创建新的远程仓库，比如叫作 MyFirstSiteRepo。
将本地仓库与刚刚创建的远程仓库关联起来，并推送所有的初始内容上去。
如果希望让其他人也能看到你的作品，记得将该远程仓库设置为公开状态（Public）。

这样你就成功地完成了从零开始创建一个小型网站并通过 GitHub 共享的过程！

本章小结

成功注册并设置了 GitHub 账户和个人资料；
理解了基本的概念区别：GitHub vs Git；
学会了如何初始化本地 Git 仓库；
掌握了如何将本地更改推送到 GitHub 远程仓库；
知道如何利用 Issues/Pull Requests/Discussions 进行团队沟通与协作。

参考来源：docs.github.com · github.com

核心概念

仓库管理

通过上一章的学习，我们已经掌握了如何初始化本地 Git 仓库并将代码推送到 GitHub 上的远程仓库。本章将进一步深入探讨如何有效地管理和维护这些仓库，让你能够更好地组织代码、协作开发以及保护项目的安全性。

为了顺利进行本章的学习，你需要确保已经完成上一章中的步骤，即拥有一个 GitHub 账号，并且至少有一个本地和远程关联的 Git 仓库。

什么是仓库管理？

仓库管理是指对存储在 GitHub 上的代码库进行的一系列操作，包括创建、修改、删除仓库，设置权限，管理分支和标签等。良好的仓库管理习惯有助于提高项目的可维护性和协作效率。

如何创建新仓库？

在 GitHub 上创建新仓库非常简单：

登录你的 GitHub 账号后，在右上角点击 "+" 号图标，然后选择 "New repository"。
填写仓库名称和其他相关信息（描述、是否公开等）。
点击 "Create repository" 按钮即可完成创建。

# 示例：假设你在本地有一个名为 my-project 的文件夹
cd my-project
git init
git add .
git commit -m "Initial commit"

预期结果：你会看到一个新的空仓库出现在你的 GitHub 主页下。

如何克隆现有仓库？

如果你想在一个新的环境中复制一个已有的 GitHub 仓库，可以使用 git clone 命令：

git clone https://github.com/username/repository.git

例如：

git clone https://github.com/user/my-first-site.git

预期结果：会在当前目录下生成一个名为 my-first-site 的文件夹，里面包含了该远程仓库的所有文件及历史记录。

如何设置权限？

合理设置权限对于保护敏感信息至关重要。GitHub 提供了几种不同的角色来分配不同的访问级别：

Owner: 对整个组织及其所有资源拥有完全控制权。
Admin: 对单个存储库具有管理员级别的访问权限。
Write: 可以推送更改到存储库中。
Read: 只能查看存储库中的内容。
None: 没有任何访问权限。

你可以通过进入特定仓库页面的 "Settings" -> "Manage access" 来添加协作者并指定他们的角色。

如何删除仓库？

当你不再需要某个仓库时，可以通过以下步骤将其删除：

进入你要删除的仓库主页。
点击右上角的 "Settings" 按钮。
向下滚动到底部找到 "Danger Zone" 部分。
点击 "Delete this repository" 并按照提示操作即可永久移除该存储库。

请注意：删除操作不可逆，请谨慎执行！

实战案例：升级个人网站项目

假设你已经在 GitHub 上托管了一个简单的个人网站项目，并且现在想要对其进行一些改进。我们可以按照以下步骤来进行：

打开之前创建的 MyFirstSiteRepo 仓库页面，在本地克隆一份最新的代码副本：
```
git clone https://github.com/yourusername/MyFirstSiteRepo.git
cd MyFirstSiteRepo
```
修改现有的 HTML/CSS 文件以更新网站设计或功能。完成后记得保存更改。
将修改后的文件添加到暂存区并提交更改到本地 Git 仓库：
```
git add .
git commit -m "Update website design"
```
最后将本地提交推送到远程 GitHub 服务器上：
```
git push origin main
```
如果希望邀请朋友一起参与开发工作，可以在 GitHub 页面上的 "Settings" -> "Manage access" 中添加他们作为协作者，并赋予相应的权限级别。

通过以上步骤，我们就成功地完成了对已有项目的升级与协作开发准备过程！

本章小结

学会了如何在 GitHub 上创建、克隆和删除新仓库；
掌握了如何设置不同用户的访问权限；
理解了如何通过版本控制系统更新和维护代码库；
经历了一次实际的项目升级流程。

参考来源：github.com · en.wikipedia.org

分支操作

我们在上一章已经学会了如何在 GitHub 上进行基本的代码管理和版本控制。接下来，我们要进一步深入学习如何使用分支来高效地管理和开发我们的项目。

基本概念

什么是分支？ 分支（Branch）是 Git 中的一个重要特性，它允许你在不影响主代码线的情况下，独立地进行开发、测试或修复错误。每个分支都是一个独立的工作空间，可以随时切换。

为什么使用分支？

并行开发：多个开发者可以同时在一个项目的不同分支上工作。
隔离变更：防止未完成或有问题的代码影响到主分支。
简化协作：通过合并请求（Pull Request），轻松整合各个分支的改动。

查看分支

首先，我们需要学会如何查看当前存在的所有分支。我们可以使用以下命令：

git branch

这条命令会列出所有本地分支，并在当前所在的分支前面加上星号 *。

如果你想查看远程仓库的所有分支，可以使用：

git branch -r

要一次性看到所有本地和远程的分支，可以用：

git branch -a

创建分支

方法一：通过 GitHub 网站创建

打开你的仓库主页。
在页面右侧找到“Branches”标签下的“Add branch”按钮。
输入新分支的名字，点击“Create branch”。

方法二：通过终端创建

假设你想创建一个新的名为 feature-login 的分支，并立即切换到这个新分支，可以执行以下命令：

git checkout -b feature-login

这条命令相当于两个操作的组合：

创建新分支 feature-login。
切换到新创建的 feature-login 分支。

如果你只想创建而不切换到该分支，可以使用：

git branch feature-login

切换分支

当你需要在不同的任务之间切换时，可以使用 git checkout 命令。例如，要切换回主分支 main：

git checkout main

或者切换到刚才创建的 feature-login 分支：

git checkout feature-login

删除分支

删除一个不再需要的本地分支时，请确保你不在该分之上。你可以先切换回其他安全的地方比如主干 main 或者其他的稳定版面。然后执行删除命令：

git branch -d feature-login

注意 -d 参数表示只有当目标被完全合并之后才会被删除。如果强制删除未合并的本地分之，则需要使用 -D 参数。

对于远程仓库中的某个不需要的分枝也可以删除:

git push origin --delete <branch_name>

例如要删除远程仓库中的 feature-login 分支:

git push origin --delete feature-login

实际案例

假设我们现在有一个需求是在网站中增加用户登录功能。我们可以按照以下步骤操作：

从现有项目克隆一份代码到本地。

创建一个新的名为 login-feature 的开发分枝，并进入这个分枝。

git clone https://github.com/yourusername/MyFirstSiteRepo.git 
cd MyFirstSiteRepo  
git checkout -b login-feature

在新的分枝上编写和调试登录功能相关的代码。

当完成并且确认没有问题后，将这个分枝推送到远程仓库：

git add .  
git commit -m "Implement user login functionality"  
git push origin login-feature

这样做的好处是我们不会干扰到主干上的稳定版本，并且可以在任何时候返回到之前的开发状态。

本章小结

理解了什么是 Git 分支及其重要性；
掌握了如何查看、创建、切换以及删除本地和远程 Git 分支；
通过实际案例练习了整个流程的应用。

参考来源：docs.github.com · blog.csdn.net

拉取请求

拉取请求（Pull Request）是将代码更改合并到项目中的建议，也是 GitHub 上的基本协作功能之一。通过拉取请求，团队成员可以在合并更改之前进行讨论和审查，从而提高代码质量和协作效率。

在开始之前，你需要确保已经熟悉了前几章提到的仓库管理和分支操作的相关内容。我们将继续使用上一章的例子，在 login-feature 分支的基础上创建一个拉取请求。

什么是拉取请求？

拉取请求是一种机制，允许开发者提议将他们的更改合并到项目的主分支或其他指定分支中。这个过程通常包括以下几个步骤：

创建分叉：首先，你需要复制（fork）原始仓库到你的个人账户下。
创建新分支：然后，在你的 fork 中创建一个新的分支来进行开发。
提交更改：在新分支上做出必要的改动，并将其推送到你的 fork。
发起拉取请求：最后，向原始仓库发起一个拉取请求，邀请其他人审查你的更改。

如何创建拉取请求？

假设我们在 login-feature 分支完成了用户登录功能的实现，并希望将这些更改合并回主仓库的 main 分支。

步骤 1: 提交更改

首先确保你在正确的分支上，并且所有更改都已经提交：

git status
git add .
git commit -m "Finalize user login functionality"
git push origin login-feature

步骤 2: 打开 GitHub 网站

访问你的 GitHub 账户页面，找到你 fork 的仓库（例如 https://github.com/yourusername/MyFirstSiteRepo）。

步骤 3: 切换到目标分支

点击页面顶部的“Branches”标签页，选择你刚刚推送的 login-feature 分支。

步骤 4: 创建拉取请求

点击页面右上角的“New pull request”按钮。GitHub 将自动检测到你最近推送的分支，并预填好基础信息。

在打开的新页面中，你可以填写一些额外的信息来帮助他人理解你的更改：

标题：简洁地描述这次修改的目的或主要内容。
描述：详细说明做了哪些改动、为什么做这些改动以及可能的影响。如果修复某个特定的问题或满足某个需求，请引用相关的 issue 编号（例如 #123）以便追踪。

步骤 5: 发起拉取请求

确认无误后，点击页面底部的“Create pull request”按钮即可提交你的拉取请求。

审查与合并

一旦拉取请求被创建出来，其他协作者就可以看到并对其进行评论和审核。他们可能会提出意见或者要求进一步改进的地方。当所有的反馈都被处理完毕并且代码得到了批准之后，拥有权限的人可以将这些更改合并到目标分支中去。

常见问题及解决方案

如果你在尝试推送代码时遇到权限错误，请确保你有足够的权限对目标仓库进行写入操作。
如果在创建拉取请求时发现无法正确识别源分支，请检查是否已成功推送本地变更至远程仓库。
在编写提交信息时尽量做到详尽准确，这样可以让评审者更容易理解和接受你的修改内容。

实际案例

回到我们的例子上来。我们已经在 login-feature 分支实现了用户登录功能，并将其推送到远程仓库。接下来我们就按照上述步骤来创建一个正式的拉取请求：

访问我的 GitHub 页面并定位到 MyFirstSiteRepo 的 fork 库。
切换到 login-feature 分支并点击“New pull request”按钮。
设置合适的标题和详细的描述信息：“Add user login feature to enhance website security”，并在描述框内补充具体的实现细节和测试情况。
最后点击“Create pull request”。

这样就完成了一次完整的从开发到提交的过程。等待其他同事审阅并通过后即可顺利地将新增的功能集成进项目的主线版本当中去了！

本章小结

理解了什么是拉取请求及其重要性；
学会了如何在 GitHub 上发起和处理拉取请求；
明确了如何撰写清晰有效的提交信息和 PR 描述；

参考来源：docs.github.com · mmcv.readthedocs.io

问题跟踪

追踪问题是我们日常开发过程中不可或缺的一部分，无论是记录bug、提出新特性需求还是讨论改进方案，都需要一个高效的问题管理系统。通过本章的学习，你将能够熟练地在GitHub上创建、管理和关闭问题，并利用这些问题来驱动项目的进展。

为了更好地理解本章内容，你需要已经掌握了基本的Git和GitHub操作，比如克隆仓库、提交更改和创建分支等。

什么是GitHub Issues？

GitHub Issues 是一种强大的工具，可以帮助你追踪各种类型的工作项。你可以用它来记录bug报告、提出新特性的建议、安排任务或者收集反馈意见。每个Issue都包含标题、详细描述以及其他相关信息，便于团队成员之间的沟通协作。

如何创建Issues？

假设你想为你的项目添加一个新的功能模块——用户评论区。首先，我们需要在GitHub上创建一个Issue来记录这个想法。

打开你的仓库页面，在右侧找到“Issues”标签并点击进入。
点击绿色的“New issue”按钮。
填写Issue的基本信息：
- Title: 添加用户评论区功能
- Description: 我们需要实现一个简单的用户评论区功能，允许注册用户发表对文章的评论。
点击“Submit new issue”按钮完成创建。

这样你就成功地创建了一个新的Issue。其他团队成员可以看到这个Issue并参与讨论。

# 示例 Issue 内容

## Title:
添加用户评论区功能

## Description:
我们需要实现一个简单的用户评论区功能，允许注册用户发表对文章的评论。

如何分配和标记Issues？

为了让其他人知道谁负责这个问题以及它的优先级和其他属性，我们可以给Issue分配负责人并加上标签。

在你刚刚创建的Issue页面中，点击右下角的“Assignees”选项卡选择一个人作为负责人。
同样地，在“Labels”部分可以添加标签来标识Issue的类型（例如：bug、enhancement）、优先级（p1, p2, p3）或其他相关信息。

什么是Sub-issues？

有时候一个问题可能分解成几个子任务才能完全解决。这时我们可以使用Sub-issues来细化工作流程。

在主Issue页面中点击“Add a sub-issue”链接。
输入子任务的具体内容并保存。

# 主 Issue 示例

## Title:
添加用户评论区功能

## Description:
我们需要实现一个简单的用户评论区功能，允许注册用户发表对文章的评论。

- [ ] 设计数据库表结构
- [ ] 编写前端界面代码
- [ ] 实现后端接口逻辑

如何使用Projects进行规划和跟踪？

除了单独管理Issues之外，我们还可以借助Projects来进行整体的工作规划和进度跟踪。

在仓库主页左侧导航栏中选择“Projects”，然后点击“New project”。
选择适合你的项目模板或从头开始自定义布局。
将相关的Issues拖拽到不同的阶段（如待办事项、正在进行、已完成）以便于可视化管理进度。
可以进一步定制字段以满足特定需求（例如：截止日期、责任人等）。

实际案例

假设我们在开发一款博客应用时遇到了一些问题需要跟踪：

用户无法上传图片到文章中。（这是一个bug）
需要增加搜索功能。（这是一个新特性）

针对以上两个问题分别创建对应的Issues，并分配给相应的开发者处理：

Bug Issue: “修复图片上传失败”
- 描述：当尝试上传图片时出现错误提示“Failed to upload file.”
- 负责人：张三
- 标签：bug, critical
Feature Issue: “增加全文搜索功能”
- 描述：希望能够在首页顶部添加一个搜索框供访客快速查找感兴趣的文章内容。
- 负责人：李四
- 标签：feature, enhancement

随后我们将这两个Issues添加到我们的Project面板中，并根据实际进展情况移动它们的位置以反映最新的工作状态。

常见报错与排查

如果你在创建或编辑Issue时遇到权限不足的问题，请确认你是否有足够的权限进行相关操作。另外需要注意的是，在填写描述信息时尽量详细准确地阐述问题的现象及影响范围，这样才能帮助他人更快地理解并解决问题所在之处。

实用技巧

使用模板化的格式书写Issue描述有助于提高效率和一致性。
定期回顾未关闭的老Issues，并评估是否仍然有效或需要重新排定优先级。
结合Milestone功能为一组相关联的任务设定共同的目标期限和里程碑节点。

本章小结

掌握了如何在GitHub上创建和管理Issues；
学会了如何分配责任人员并对Issues进行分类标记；
理解了Sub-Issues的概念及其应用场景；
探索了如何利用Projects工具辅助项目规划与进度跟踪；

参考来源：docs.github.com · docs.github.com

进阶能力

项目管理

项目管理是软件开发过程中不可或缺的一部分，它帮助团队有效地组织和追踪任务，确保项目的顺利进行。通过本章的学习，你将掌握如何在GitHub上使用Projects来管理和优化你的工作流程。

前置知识

在开始之前，你需要熟悉GitHub的基本操作，比如创建仓库、分支操作以及拉取请求等。如果你已经完成了前面几章的学习，那么这些应该都不是问题。

什么是GitHub Projects？

GitHub Projects是一个强大的工具集，可以帮助开发者和团队管理者组织和跟踪项目中的各项工作。你可以创建不同的视图（Boards, Tables, 和 Canvas），来适应各种项目需求。

创建一个新的Project

打开你的仓库页面。
点击右上角的<> Code按钮旁边的三个点图标。
选择Projects -> New Project。
输入项目名称和描述，然后点击Create project。

添加卡片到Board视图

在新创建的Project页面中，默认进入的是Board视图。
点击左侧的列名（例如"To do"）下的绿色加号按钮。
在弹出窗口中输入卡片内容，并可以关联Issue或者Pull Request。
点击Add card完成添加。

| 列     | 卡片内容           |
|--------|--------------------|
| To do  | 设计数据库架构     |
| Doing  | 编写用户注册接口   |
| Done   | 用户登录功能实现   |

移动卡片更改状态

你可以拖拽卡片在不同列之间移动，以此来更新任务的状态。比如当设计数据库架构完成后，可以将其从“To do”列移到“Doing”列。

如何使用Table视图？

除了Board视图外，GitHub还支持Table视图来进行更详细的项目管理。

在Project页面上方点击Switch to table view切换到表格模式。
默认情况下会有几个预设字段如Title、Assignees等，你可以根据需要添加更多自定义字段。
点击右侧的绿色加号按钮添加新的行数据。
填入相关信息后保存即可。

| Title            | Assignee | Status    | Due Date       |
|------------------|----------|-----------|----------------|
| 数据库设计       | 张三     | In Progress | 2023-09-15     |
| 用户注册接口编写 | 李四     | Not Started | 2023-09-20     |

常见报错与排查

如果你发现无法创建新的Project或者移动卡片时遇到权限问题，请检查你是否具有相应的权限。通常只有仓库的所有者或管理员才有权执行这些操作。

实用技巧

使用自动化工具（如GitHub Actions）来自动同步Issues到Projects中。
设置提醒以便及时处理即将到期的任务。
定期回顾并调整Projects设置以适应变化的需求。

示例：管理一个小型Web应用开发项目

假设你要开发一个小型的博客网站，并且希望使用GitHub Projects来管理整个过程。以下是具体的步骤：

创建一个新的Repository命名为"MyBlog"。
进入Repository后按照上述方法创建一个新的Project，并命名为“My Blog Development”。
将所有的开发任务分解成多个子任务，并作为卡片分别添加到对应的列中（如To do, Doing, Review, Done）。
分配每个任务的责任人，并设置截止日期以便跟踪进度。

通过这种方式，你可以清晰地看到所有的工作项及其进展状态，并能够高效地协同工作团队成员一起推进项目的完成。

本章小结

掌握了如何在GitHub上创建和配置Projects；
学会了如何使用Board和Table两种视图进行项目管理；
理解了如何将Tasks分配给不同的责任人并设置截止日期；
探索了一些实用技巧来提升工作效率。

参考来源：github.com · en.wikipedia.org

GitHub Actions

自动化流程是现代软件开发不可或缺的一部分，而 GitHub Actions 正好可以帮助我们实现这一点。通过 GitHub Actions，我们可以自动化构建、测试、部署等任务，从而提高开发效率。读完本章后，你将能够理解 GitHub Actions 的基本概念，并学会如何编写和配置简单的 Workflow 文件。

为了更好地理解和使用 GitHub Actions，你需要对 Git 和 GitHub 基本操作有一定的了解。确保你已经有一个 GitHub 账号并且熟悉如何创建和管理 Repository。

什么是 GitHub Actions？

GitHub Actions 是一种持续集成（CI）和持续交付（CD）服务，允许你在每次代码提交或事件触发时自动运行脚本。这些脚本可以用来构建、测试、打包你的项目，甚至发布到生产环境中。

如何使用 GitHub Actions？

第一步：创建一个 Workflow 文件

Workflow 文件定义了一系列的 Job 和 Step，它们描述了 CI/CD 流程的具体步骤。Workflow 文件需要放在 .github/workflows 目录下。

我们先创建一个简单的 Workflow 文件来演示如何构建一个 Python 项目：

name: Python application test

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v3
      with:
        python-version: '3.8'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8 pytest coverage
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest

在这个例子中：

name 定义了 Workflow 的名称。
on 描述了触发条件，在这里当推送到 main 分支或者向 main 分支发起 Pull Request 时都会触发。
jobs 定义了一个名为 build 的 Job。
runs-on 指定了运行该 Job 的虚拟机环境为 Ubuntu 最新版本。
steps 列出了 Job 中的具体步骤：
- 使用 actions/checkout@v3 来检出代码。
- 使用 actions/setup-python@v3 来安装指定版本的 Python。
- 安装依赖包。
- 使用 Flake8 进行代码风格检查。
- 使用 Pytest 进行单元测试。

第二步：推送 Workflow 文件到 Repository

将上面的 YAML 内容保存为 .github/workflows/python-app.yml 并提交到你的 Repository 中：

mkdir .github/workflows/
nano .github/workflows/python-app.yml   # 或者你喜欢的编辑器打开文件并粘贴内容
git add .github/workflows/python-app.yml 
git commit -m "Add Python application test workflow"
git push origin main                    # 如果你的默认分支不是 main，请相应修改命令中的分支名

一旦你推送了这个文件，GitHub 就会根据定义的触发条件自动运行这个 Workflow。你可以在 Repository 页面的 "Actions" 标签下查看 Workflow 的运行情况。

易错点与排查

常见的错误包括：

语法错误：YAML 对缩进非常敏感，任何多余的空格都可能导致解析失败。如果遇到这样的问题，请仔细检查 YAML 文件的格式。
权限问题：确保你的账户有足够的权限来创建和运行 Workflows。一般情况下，默认权限是可以满足需求的。

实际案例

假设我们在开发一个 Flask 应用程序，并且希望通过 GitHub Actions 自动化测试过程。我们可以基于前面的例子稍作修改：

name: Flask application test

on:
  push:
    branches:
      - develop       # 我们选择监听 develop 分支而不是 main 分支

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v3
      with:
        python-version: '3.9'            # 更新 Python 版本为 3.9
    
    # 添加 Flask 特定的操作步骤    
    - name: Install dependencies        
      run: |
        python -m pip install --upgrade pip  
        pip install flask pytest         
        
    # 启动 Flask 应用并进行测试   
    - name: Run tests                  
      env:
         FLASK_APP=test_app.py          # 设置环境变量指向测试应用入口      
         FLASK_ENV=development          
      run: |                            
         flask db upgrade               # 升级数据库模式              
         pytest                         # 执行测试套件

在这个例子中，我们不仅进行了基本的安装和测试步骤，还增加了启动 Flask 应用并升级数据库模式的部分。

本章小结

理解了 GitHub Actions 是什么以及它能做什么。
学会了如何编写基础的 Workflow 文件，并将其推送到 Repository 中。
掌握了常见的易错点及排查方法。
实践了一个实际案例来巩固所学知识。

参考来源：github.com · en.wikipedia.org

包管理

通过本章的学习，你可以掌握如何在 GitHub 上管理和分发软件包。阅读完毕后，你不仅能理解 GitHub Packages 的用途，还能学会如何创建、发布和使用这些软件包。

在开始之前，你需要确保已经有一个 GitHub 账户，并且熟悉基本的 Git 和 GitHub 操作。此外，还需要安装好 Python 及 pip 工具。

什么是 GitHub Packages？

GitHub Packages 是一项软件包托管服务，允许开发者和团队在 GitHub 上发布和共享软件包。你可以将各种类型的软件包存储在这里，并作为项目的依赖项使用。这使得版本控制更加方便，同时也简化了协作流程。

如何创建一个简单的 Python 包

首先，我们需要创建一个简单的 Python 包。假设我们要创建一个名为 my_package 的包：

mkdir my_package
cd my_package
touch __init__.py
echo 'def greet(): return "Hello from my package!"' >> __init__.py

接着，我们为这个包添加一些元数据信息：

cat <<EOF > setup.py
from setuptools import setup, find_packages

setup(
    name='my_package',
    version='0.1',
    packages=find_packages(),
    description='A simple example package',
    author='Your Name',
    author_email='your.email@example.com',
)
EOF

发布到 GitHub Packages

为了将我们的包发布到 GitHub Packages，我们需要先登录到 GitHub 并生成一个 Personal Access Token（PAT）。访问 GitHub Tokens 页面，点击“Generate new token”，勾选 write:packages 权限并生成令牌。

然后，在你的终端中设置认证信息：

export USERNAME=<your_github_username>
export TOKEN=<your_generated_token>

# 登录到 GitHub Packages (注意替换 <owner> 为你自己的用户名或组织名)
echo $TOKEN | docker login ghcr.io -u $USERNAME --password-stdin

构建并推送 Docker 镜像（这里以 Docker 为例）：

docker build . -t ghcr.io/<owner>/my-package:v0.1
docker push ghcr.io/<owner>/my-package:v0.1

对于纯 Python 包，则需要修改 .pypirc 文件来进行上传：

[distutils]
index-servers =
    pypi

[pypi]
repository: https://upload.pypi.org/legacy/
username: __token__
password: ${PYPI_TOKEN}

[gh-test-repo]
repository: https://upload.pypi.org/legacy/
username: __token__
password: ${GITHUB_TOKEN}

最后执行上传命令：

python setup.py sdist bdist_wheel 
twine upload dist/* -r gh-test-repo

使用已发布的包

其他用户可以通过以下方式安装你的包：

对于 PyPI 托管的包

pip install my_package==0.1 --extra-index-url=https://pypi.org/simple/ --extra-index-url=https://<username>:<token>@pypi.pkg.github.com/<username>

对于 Container Registry 托管的镜像

docker pull ghcr.io/<owner>/my-package:v0.1

常见问题与排查技巧

权限错误：如果遇到权限问题，请检查你的 PAT 是否包含正确的权限，并且你在正确的命名空间下操作。
网络问题：有时候由于网络原因导致无法连接到 GitHub Packages，请检查网络连接或者稍后再试。
版本冲突：当多个版本共存时，请明确指定所需的版本号以避免潜在的问题。

示例：分享一个自定义的日志模块

假设你想分享一个自定义的日志模块给同事使用。按照上述步骤创建并发布该模块后，在他们的项目中只需简单地添加一行导入语句即可引入你的日志功能。

通过这样一个过程，你会发现整个发布和使用的流程其实并不复杂，并且能够极大地提升团队内部协作效率。

本章小结

学习了如何创建和打包 Python 项目。
掌握了如何利用 GitHub Packages 发布和管理软件包。
理解了如何正确配置认证信息以便安全地上传下载资源。
实践了一个具体的案例来加深对相关概念的理解。

参考来源：docs.github.com · supperthomas-wiki.readthedocs.io

安全设置

保护好你的 GitHub 账户和个人数据非常重要，今天我们要聊聊如何进行安全设置，确保你的账户和仓库都处于安全状态。完成本章的学习后，你能熟练掌握如何启用两步验证、管理 SSH 密钥以及查看审核日志等基本的安全措施。

前置知识

你需要已经有一个 GitHub 账户并且知道如何登录。如果你还没有账号，可以先去注册一个。

启用两步验证

两步验证（2FA）可以在密码泄露的情况下增加一层额外的安全防护。下面是开启两步验证的步骤：

登录 GitHub 并点击右上角的个人头像。
选择 Settings。
在左侧菜单找到并点击 Security。
点击 Two-factor authentication 下面的 Enable two-factor authentication 按钮。
按照屏幕上的指示选择接收验证码的方式（手机短信或应用生成的一次性密码）。
设置完成后记得保存你的恢复密钥。

这样即使有人知道了你的密码也无法登录你的账户。

管理 SSH 密钥

SSH 密钥是一种比密码更安全的身份验证方式，适用于通过 Git 进行远程操作时的身份确认。以下是添加 SSH 密钥到 GitHub 的步骤：

生成新的 SSH 密钥对（如果还没有的话）。打开终端并输入以下命令：
```
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
按提示操作，通常可以直接按回车键接受默认设置。
将公钥添加到 GitHub：
- 复制公钥内容：
```
cat ~/.ssh/id_rsa.pub
```
- 登录 GitHub 并进入 Settings -> SSH and GPG keys -> New SSH key。
- 输入一个标题描述这个密钥的作用（比如“我的笔记本电脑”），然后粘贴复制的公钥内容。
- 点击 Add SSH key 完成添加。

查看审核日志

审核日志可以帮助你追踪谁访问了你的账户以及进行了哪些操作。以下是查看审核日志的方法：

登录 GitHub 并进入 Settings -> Security -> Audit log。
在这里你可以看到最近的操作记录，包括时间、IP 地址和动作类型等详细信息。

实际案例：保护敏感项目

假设你正在开发一个商业项目，并且不想让未经授权的人接触到源码。你可以采取以下措施提高安全性：

启用两步验证：防止他人通过仅凭密码就登录账户。
私有仓库：将项目设为私有仓库以限制访问权限。
精细的权限管理：根据需要分配不同的角色给团队成员（如管理员、写入者、只读用户等）。
定期审查活动日志：监控是否有异常行为发生。

常见问题与排查技巧

忘记两步验证恢复密钥：尽快联系 GitHub 支持寻求帮助找回账户访问权。
无法添加 SSH 密钥：检查是否已登录正确的账户，并且提供的公钥格式正确无误。
找不到审核日志：确保你有足够的权限查看组织级别的审计日志；如果是个人账户，则只能查看自己的活动记录。

本章小结

学会了如何启用两步验证增强账户安全性。
掌握了生成和使用 SSH 密钥的方法，提高了身份认证的安全级别。
知道了如何查看审核日志来监控账户活动，及时发现潜在风险。

参考来源：docs.github.com · docs.github.com

部署运维

Webhooks 配置

配置 Webhooks 让你在代码库中有重要的更新时自动触发外部服务，比如持续集成/持续部署（CI/CD）系统。通过本章的学习，你能学会如何在 GitHub 上设置 Webhooks，并理解它们的工作原理。

首先，你需要知道一些基本概念。Webhooks 是一种 HTTP 回调机制，当指定的事件发生在你的 GitHub 仓库时，GitHub 会向你设定的 URL 发送 HTTP POST 请求。常见的应用场景包括自动构建和测试代码、同步数据到其他系统等。

步骤详解

1. 打开 Webhooks 设置

登录 GitHub 后，找到你要配置 Webhook 的仓库主页。点击页面右上角的 Settings 按钮，然后在左侧菜单中选择 Webhooks。

2. 添加新的 Webhook

点击页面上的 Add webhook 按钮。你会看到几个需要填写的信息字段：

Payload URL: 这是你希望 GitHub 将数据发送到的服务地址。例如：http://192.168.1.2:8081/jenkins/github-webhook
Content type: 数据格式通常可以选择 application/json。
Secret: 这是一个可选的安全字段，用来验证请求确实来自 GitHub。建议填写一个随机生成的复杂字符串。
Which events would you like to trigger this webhook?: 你可以选择特定事件（如 push、pull request 等）或者所有事件。

3. 完成配置

填写好以上信息后，点击页面底部的 Add webhook 按钮即可完成配置。

示例操作

假设我们要为一个名为 my-project 的仓库配置一个简单的 Webhook 到 Jenkins CI 系统：

# 假设我们的 Jenkins 地址是 http://192.168.1.2:8081/jenkins/github-webhook/

按照上述步骤操作：

进入 my-project 仓库主页 -> Settings -> Webhooks -> Add webhook。
Payload URL 输入：http://192.168.1.2:8081/jenkins/github-webhook/
Content type 选择：application/json
Secret 字段输入：your_random_secret_key_here
Which events would you like to trigger this webhook? 选择：Just the push event
最后点击 Add webhook 即完成配置。

注意事项与常见问题

权限问题：只有具有相应权限的用户才能在仓库上添加或修改 Webhooks。
网络可达性：确保你的服务器能够被互联网访问，并且防火墙规则允许来自 GitHub 的请求。
调试方法：如果 Webhook 不工作，可以查看 GitHub 提供的日志信息来诊断问题。具体路径为：Settings -> Webhooks -> 点击具体的 Hook 名称下的 Recent deliveries。
速率限制：GitHub 对每个存储库或组织的 Webhook 数量有限制（最多 20 个）。如果超过限制，可以考虑使用代理服务器来分发请求。

实际案例

想象一下你正在维护一个开源项目，并希望每次有人推送新代码时自动触发 Travis CI 构建流程。你可以按照上述步骤在 GitHub 上配置一个指向 Travis CI 的 Webhook，并选择只监听 push 和 pull request 事件。这样一来，每当有开发者提交代码或者发起拉取请求时，Travis CI 都会自动启动构建过程并报告结果。

本章小结

学习了什么是 Webhooks 及其作用。
掌握了如何在 GitHub 上配置 Webhooks 的具体步骤。
注意到了一些常见的错误及排查方法。
理解了实际应用中的使用场景和好处。

参考来源：weiliang-ms.github.io · docs.github.com

GitHub CLI 使用

通过本章的学习，你可以掌握如何使用 GitHub CLI 直接在命令行中操作 GitHub，从而提高工作效率。读完之后，你不仅能熟悉常用的 GitHub CLI 命令，还能学会如何配置和使用它们。

为了顺利进行本章的学习，你需要已经安装好 Git 和 GitHub CLI。如果你还没有安装 GitHub CLI，可以从 GitHub CLI 的安装页面获取详细的安装指南。

什么是 GitHub CLI？

GitHub CLI 是一个开源工具，让你可以直接在命令行中使用 GitHub 的各项功能。相比于在浏览器中操作，GitHub CLI 可以帮助你更快地完成任务，并减少频繁切换上下文的时间。

如何安装 GitHub CLI？

根据你的操作系统不同，安装方法也会有所不同：

macOS

brew install gh

Windows

可以通过 Chocolatey 安装：

choco install gh

Linux

不同的发行版有不同的包管理器，这里以 Debian/Ubuntu 为例：

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
sudo apt-add-repository https://cli.github.com/packages
sudo apt update
sudo apt install gh

认证登录

安装完成后，你需要先认证登录才能使用大部分功能。运行以下命令：

gh auth login

按提示选择合适的认证方式即可。

查看仓库信息

如果你想查看某个仓库的详情或 README 文件，可以使用 gh repo view 命令。例如：

gh repo view octocat/Hello-World

如果你想在浏览器中直接打开该仓库页面，则可以加上 --web 参数：

gh repo view octocat/Hello-World --web

当你在已克隆的本地 Git 仓库目录下时，可以省略 OWNER/REPO 参数：

cd path/to/repo-directory/
gh repo view --web

创建新仓库

如果你想在 GitHub 上创建一个新的空仓库，并可以选择是否克隆到本地，可以运行：

gh repo create my-new-repo --public/--private --confirm --source=.

这里的 --public 或 --private 参数用来设置仓库的可见性；--confirm 表示确认创建；--source=. 表示从当前目录推送到新建的远程仓库。

管理 Issues

你可以列出特定存储库的所有开放问题，并过滤条件如下所示：

按分配人筛选问题：gh issue list --assignee @me
按作者筛选问题：gh issue list --author username

同样，在已克隆的本地 Git 仓库目录下时，可以省略 --repo OWNER/REPO 参数。

管理 Pull Requests

类似于 Issues 的管理方式，你可以列出特定存储库的所有开放拉取请求，并根据需求进行过滤：

按作者筛选 PR：gh pr list --author @me
按状态筛选 PR（open/closed/all）：gh pr list --state open

同样，在已克隆的本地 Git 仓库目录下时，默认会关联对应的远程仓库。

使用 Codespaces

Codespaces 是一种开发环境即服务（DevOps as a Service），可以在云端编写代码而无需设置开发环境。以下是相关命令示例：

创建 codespace：gh codespace create
显示现有 codespace：gh codespace list
在 VS Code 的 Web 版本中打开 codespace：gh codespace code -w

自定义配置与别名

你可以自定义编辑器和其他偏好设置。例如更改默认编辑器为 Vim:

gh config set editor vim

对于经常使用的命令还可以设置快捷别名:

gh alias set co checkout -s # 设置 'co' 作为 'checkout' 的简写形式。

这样可以帮助你更高效地使用 GitHub CLI。

实际案例

假设你现在有一个名为 my-project 的本地项目，并希望将其推送到新的公共 GitHub 仓库。我们可以按照以下步骤操作：

初始化并提交本地项目：

cd path/to/my-project/
git init && git add . && git commit -m "Initial commit"

使用 GitHub CLI 创建新仓库并将本地项目推送到其中：
```
gh repo create my-project --public --source=. --push 
```
此命令会在你的账户下创建一个名为 my-project 的公开仓库，并将当前项目的代码推送到该远程分支上。

列出所有已创建的问题和拉取请求:

gh issue list # 查看问题列表   
gh pr list     # 查看PR列表

当然你还可以随时更新你的项目并通过命令行发起新的 PR 请求等...

常见错误及排查方法

未认证：当你尝试执行需要身份验证的操作时，请确保已正确登录。
找不到存储库：检查提供的用户名和存储库名称是否正确无误。
权限不足：确保你拥有对目标资源（如 Issue、PR）的操作权限。

实用技巧

使用 -h|--help: 大多数子命令都支持此选项来获取更多帮助信息。
使用 -R|--repo OWNER/REPO: 快速指定要操作的目标存储库。
使用 -W|--web: 直接在浏览器中打开相关的网页界面。

本章小结

学习了如何安装和配置 GitHub CLI。
掌握了基本的命令用法来查看、创建和管理 GitHub 资源。
注意了一些常见的错误及其解决办法。
实践了一个完整的流程来展示如何利用 GitHub CLI 来处理日常开发任务。

参考来源：docs.github.com · cli.github.com

实战

Gist 分享

通过前几章的学习，你现在应该已经熟悉了如何在 GitHub 上管理和协作代码了。今天我们要聊的是 Gist 分享，这是一种快速分享代码片段、笔记和其他文本的好方式。读完这一章后，你会知道如何创建、编辑和分享 Gist，还能理解它们的可见性设置。

前置知识

你需要有一个 GitHub 账户，并且最好已经安装了 GitHub CLI (gh)，这样可以更方便地进行一些操作。不过我们也会介绍如何通过网页界面来完成相同的工作。

什么是 Gist？

Gist 是一种简单的托管服务，允许你分享代码片段、笔记或其他文本。你可以选择让这些内容公开或保密。Gist 实际上是一个小型的 Git 仓库，因此你可以像对待普通仓库一样对其进行版本控制和协作。

如何创建 Gist？

方法一：通过网页界面

登录你的 GitHub 账户。
访问 https://gist.github.com。
在“Description”框中输入描述信息。
在文件名框中输入文件名（例如 example.py）。
在编辑器中输入你想分享的内容。
选择“Public”或“Secret”，然后点击“Create gist”。

方法二：通过 GitHub CLI

打开终端并确保已登录 GitHub CLI：
```
gh auth login
```

使用以下命令创建一个新的公共 Gist：

echo "print('Hello, World!')" | gh gist create --desc "My first gist" --filename hello_world.py

如果你想创建一个秘密的 Gist，只需添加 --secret 参数：

echo "This is a secret note." | gh gist create --desc "A secret note" --filename secret_note.txt --secret

如何编辑和修改 Gist？

方法一：通过网页界面

找到你要编辑的 Gist 并点击进入。
点击右上角的铅笔图标进行编辑。
修改完成后，滚动到底部并点击“Update gist”。

方法二：通过 GitHub CLI

获取你要编辑的 Gist ID 或 URL。

使用以下命令来编辑指定的 Gist 文件：

gh gist edit <gist-id-or-url> --add-file new_file.md="## New File Content"

如果你想修改现有文件的内容：

echo "Updated content here." | gh gist edit <gist-id-or-url> --update-file existing_file.py=

如何共享 Gist？

一旦你创建了一个公共的 Gist，任何人都可以通过复制其 URL 来访问它。对于秘密的 Gist，只有你知道 URL 的人才能看到它。

发送链接给他人

简单地复制 Gist 页面上的 URL 并发送给其他人即可。

嵌入到其他网站或文档中

许多平台支持嵌入 HTML 内容。你可以在 Gist 页面找到嵌入代码，并将其粘贴到支持 HTML 的地方。

易错点及排查方法

权限问题：如果你尝试编辑不属于你的公开 Gist，会收到权限拒绝错误。请确认你是在正确的页面进行操作或者联系原作者请求权限。
URL 错误：如果别人无法访问你的秘密 Gist，请确保他们确实拥有正确的 URL，并且是登录状态下的合法用户。
格式问题：在某些情况下，Gist 中的内容可能不会正确显示为代码块。确保你在创建时选择了合适的语法高亮选项。

示例场景

假设你在工作中遇到了一个有趣的技术难题，并想记录下来以便日后查阅或与其他开发者交流。你可以按照以下步骤操作：

创建一个新的公共 Gist，并详细描述这个问题及其解决方案。
将相关代码片段添加进去，并使用适当的编程语言标记以获得语法高亮效果。
最后，在团队内部论坛或聊天群组中分享这个 Gist 的链接，供同事们参考讨论。

本章小结

学习了如何通过网页界面和 GitHub CLI 创建、编辑和删除 Gists。
理解了公共和秘密两种类型的 Gists 及其适用场景。
掌握了如何共享和嵌入 Gists 到其他平台上。
注意了一些常见的错误及其解决办法。

参考来源：gist.github.com · docs.github.com

使用模板

编写和使用模板可以帮助你简化日常的工作流程，无论是创建新的工作流还是编写拉取请求。通过本章的学习，你不仅能掌握如何为项目创建这些模板，还能提高协作效率。

前置知识

你需要有一个 GitHub 账户。
你应该已经熟悉如何创建和管理 GitHub 仓库。
对 Git 和 GitHub 的基本操作有所了解会有帮助。

工作流模板

GitHub 提供了许多预设的工作流模板来帮助你快速启动自动化任务。比如，如果你想为 Python 项目设置持续集成（CI），可以使用现有的 CI 模板。

如何使用工作流模板

打开你的 GitHub 仓库主页。
点击顶部的 Actions 标签。
在 Actions 页面中，你会看到一系列推荐的工作流模板。你可以根据需要选择一个点击“Set up this workflow”。

# 示例：设置 Python 应用程序的 CI 流程
name: Python application test

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.9
      uses: actions/setup-python@v2
      with:
        python-version: '3.9'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8 pytest
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest tests/

以上是一个简单的 Python 应用程序 CI 测试的工作流示例。它会在每次推送代码时自动执行语法检查和单元测试。

拉取请求模板

拉取请求模板能让你规范地填写 PR 描述，便于审查者理解你的改动内容。

如何添加拉取请求模板

导航到你的 GitHub 仓库主页。
在文件列表上方，点击“Add file”下拉菜单，然后选择“Create new file”。
输入文件路径 .github/pull_request_template.md 并开始编辑文件内容。你可以根据项目的特性自定义这个模板。

# 示例：拉取请求模板内容

## 拉取请求目的

请简要描述此 Pull Request 的主要修改内容以及为何作出这些修改。

## 修改详情

列出具体的变更点，并解释每个变更的理由。

## 测试情况

说明你已经进行了哪些测试以验证这些更改的有效性和稳定性。

## 截图或视频演示（如果有）

提供必要的截图或录制的操作视频来辅助说明此次修改的效果。

保存这个文件后，当你在该仓库发起新的拉取请求时，默认就会加载这个模板内容作为 PR 正文的基础框架。

实际应用案例

假设你在开发一个开源项目，并希望所有贡献者的 Pull Requests 都能遵循一致的格式以便于管理和审核。你可以按照上述步骤为项目添加一个详细的拉取请求模板，并引导参与者在提交 PR 前认真填写相关信息。

本章小结

学习了如何利用 GitHub 提供的工作流模板加速项目的自动化构建过程。
掌握了如何在仓库中创建自定义的拉取请求模板以统一 PR 内容格式。
理解了使用这些模板的好处及其应用场景。

参考来源：docs.github.com · docs.github.com