强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Git 完全指南 / 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/CDGitHub Actions 工作流
Bug 追踪Issues + Issue 模板
项目管理GitHub Projects + 自动化
依赖安全Dependabot + CodeQL
文档站点GitHub Pages + Actions

扩展阅读


🔗 上一章14 - Git LFS | 下一章16 - GitLab 工作流