15 - GitHub 工作流:PR、Actions、Issues、Projects
第十五章:GitHub 工作流
GitHub 不仅是代码托管平台,更是完整的软件开发生态系统。
15.1 Pull Request (PR)
15.1.1 创建 PR
# 方法 1:使用 gh CLI(推荐)
$ git push origin feature/login
$ gh pr create --title "feat: add login page" --body "## 变更说明\n- 添加用户登录页面\n- 实现 JWT 认证"
# 方法 2:在 GitHub 网页创建
# 方法 3:使用 hub CLI
$ hub pull-request -m "feat: add login page"
15.1.2 PR 模板
创建 .github/pull_request_template.md:
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他
## 变更说明
<!-- 描述你的变更 -->
## 关联 Issue
<!-- 关联的 Issue 编号 -->
## 测试说明
<!-- 如何测试这些变更 -->
## 截图(如有)
15.1.3 PR 工作流
# 1. 创建功能分支
$ git switch -c feature/user-auth main
# 2. 开发并提交
$ git add -A && git commit -m "feat: implement user authentication"
# 3. 推送到远程
$ git push -u origin feature/user-auth
# 4. 创建 PR
$ gh pr create --title "feat: implement user authentication" \
--body "Implement JWT-based authentication system" \
--reviewer @teamlead,@senior-dev \
--label "feature,security"
# 5. 查看 PR 状态
$ gh pr status
# 6. 合并 PR(审查通过后)
$ gh pr merge --squash
# 7. 删除远程分支
$ git push origin --delete feature/user-auth
15.1.4 PR Review
# 查看 PR 列表
$ gh pr list
# 检出 PR 进行本地测试
$ gh pr checkout 123
# 提交审查意见
$ gh pr review 123 --approve
$ gh pr review 123 --request-changes --body "需要修改..."
$ gh pr review 123 --comment --body "代码看起来不错,但是..."
# 查看 PR 的 diff
$ gh pr diff 123
15.2 GitHub Actions
15.2.1 基本工作流
创建 .github/workflows/ci.yml:
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18.x, 20.x]
steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- run: npm ci
- run: npm run lint
- run: npm test
- run: npm run build
15.2.2 常用 Actions 工作流
自动部署到 GitHub Pages
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- uses: actions/configure-pages@v4
- uses: actions/upload-pages-artifact@v3
with:
path: './dist'
- id: deployment
uses: actions/deploy-pages@v4
自动发布 npm 包
name: Release
on:
push:
tags: ['v*']
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- run: npm ci && npm run build
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
自动创建 Release
name: Create Release
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/create-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ github.ref }}
generate_release_notes: true
15.2.3 Actions 变量和密钥
# 设置仓库密钥
$ gh secret set NPM_TOKEN --body "your-npm-token"
# 设置环境密钥
$ gh secret set DEPLOY_KEY --env production --body "your-deploy-key"
# 设置变量
$ gh variable set MY_VAR --body "value"
在工作流中使用:
steps:
- name: Use secret
run: echo "Using token..."
env:
TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Use variable
run: echo "Value is ${{ vars.MY_VAR }}"
15.3 Issues
15.3.1 Issue 管理
# 创建 Issue
$ gh issue create --title "Bug: 登录超时" --body "详细描述..." --label "bug,urgent"
# 列出 Issues
$ gh issue list
$ gh issue list --label "bug" --state open
# 查看 Issue
$ gh issue view 42
# 关闭 Issue
$ gh issue close 42
# 重新打开
$ gh issue reopen 42
# 添加评论
$ gh issue comment 42 --body "已修复,请验证"
15.3.2 Issue 模板
创建 .github/ISSUE_TEMPLATE/bug_report.md:
---
name: Bug Report
about: 报告一个 Bug
labels: bug
---
## Bug 描述
<!-- 清晰描述 bug 是什么 -->
## 复现步骤
1. 打开 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 出现错误
## 期望行为
<!-- 描述你期望发生什么 -->
## 实际行为
<!-- 描述实际发生了什么 -->
## 环境信息
- OS: [e.g., Windows 11]
- Browser: [e.g., Chrome 120]
- App Version: [e.g., 1.0.0]
15.4 GitHub Projects
# 创建项目
$ gh project create --title "Sprint 1" --owner "@me"
# 查看项目列表
$ gh project list --owner "@me"
# 添加 Issue 到项目
$ gh project item-add 1 --owner "@me" --url https://github.com/user/repo/issues/42
# 查看项目状态
$ gh project view 1 --owner "@me"
15.5 GitHub CLI 速查表
| 命令 | 说明 |
|---|---|
gh repo clone | 克隆仓库 |
gh repo create | 创建仓库 |
gh pr create | 创建 PR |
gh pr merge | 合并 PR |
gh pr review | 审查 PR |
gh pr checks | 查看 CI 状态 |
gh issue create | 创建 Issue |
gh issue list | 列出 Issues |
gh workflow run | 触发工作流 |
gh secret set | 设置密钥 |
gh release create | 创建 Release |
gh api | 调用 GitHub API |
15.6 GitHub 安全最佳实践
# Dependabot 自动更新依赖
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# 代码扫描
# .github/workflows/codeql.yml
name: CodeQL
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: github/codeql-action/init@v3
with:
languages: javascript
- uses: github/codeql-action/analyze@v3
业务场景
| 场景 | 推荐方案 |
|---|---|
| 团队代码审查 | PR + 必需审查者 + 分支保护 |
| 自动化 CI/CD | GitHub Actions 工作流 |
| Bug 追踪 | Issues + Issue 模板 |
| 项目管理 | GitHub Projects + 自动化 |
| 依赖安全 | Dependabot + CodeQL |
| 文档站点 | GitHub Pages + Actions |
扩展阅读
🔗 上一章:14 - Git LFS | 下一章:16 - GitLab 工作流