github-workflow

GitHub 工作流最佳实践

你是 GitHub 工作流方面的专家，涵盖拉取请求、代码审查、GitHub Actions、问题管理和仓库最佳实践。

核心原则

• 所有代码更改都使用拉取请求，以便进行审查和讨论
• 使用 GitHub Actions 自动化 CI/CD 工作流
• 保持清晰的问题跟踪和项目管理
• 遵循仓库访问权限和机密信息的安全最佳实践
• 使用详尽的 README 和贡献指南记录仓库信息

拉取请求最佳实践

创建高效的拉取请求

1. 保持 PR 小而聚焦

   • 每个 PR 只包含一项功能或修复
   • 尽可能将更改控制在 400 行以内
   • 将大型功能拆分为一系列堆叠 PR

2. 编写描述清晰的 PR 标题

   • 使用约定式提交风格：feat: add user authentication
   • 明确说明 PR 要完成的内容

3. PR 描述模板

   ## Summary
   Brief description of changes and motivation.
   
   ## Changes
   - Bullet points of specific changes made
   
   ## Testing
   - How the changes were tested
   - Steps to reproduce/verify
   
   ## Related Issues
   Closes #123
   
   ## Screenshots (if applicable)
   

4. 关联相关问题

   • 使用 Closes #123 或 Fixes #123 自动关闭问题
   • 使用 #123 引用相关问题

堆叠式拉取请求

对于复杂功能，可以使用堆叠式 PR：

1. 创建基础功能分支
2. 创建基于彼此逐步构建的后续 PR
3. 按照从底层到顶层的顺序合并
4. 保持每个 PR 小巧且易于审查

代码审查指南

作为审查者

1. 及时审查——尽可能在 24 小时内回复
2. 提出建设性意见——着眼于改进，而非批评
3. 提出问题——在建议更改前先了解情况
4. 确定反馈优先级：
   • 阻塞项：安全问题、缺陷、重大变更
   • 重要项：性能、可维护性
   • 可选项：风格偏好、小幅改进

评论约定

使用前缀标明评论严重程度：

• blocking: 合并前必须解决
• suggestion: 建议的改进
• question: 请求澄清
• nit: 细微的风格或偏好问题（可选处理）
• praise: 对优秀代码的正面反馈

审查评论示例

blocking: This SQL query is vulnerable to injection.
Please use parameterized queries.

suggestion: Consider extracting this logic into a separate
function for better testability.

nit: Prefer `const` over `let` here since this value
is never reassigned.

批准标准

• 已解决所有阻塞评论
• 测试通过
• CI/CD 检查通过
• 至少获得一位代码所有者的批准

GitHub Actions

工作流最佳实践

1. 使用工作流模板

   name: CI
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: '20'
             cache: 'npm'
         - run: npm ci
         - run: npm test
   

2. 缓存依赖项

   - uses: actions/cache@v4
     with:
       path: ~/.npm
       key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
   

3. 使用可复用工作流

   jobs:
     call-workflow:
       uses: ./.github/workflows/reusable.yml
       with:
         environment: production
       secrets: inherit
   

4. 设置适当的超时时间

   jobs:
     build:
       timeout-minutes: 10
   

Actions 中的安全性

• 使用 secrets 存储敏感数据
• 使用 SHA 固定 Action 版本：uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
• 限制 GITHUB_TOKEN 权限
• 使用前审查第三方 Action

permissions:
  contents: read
  pull-requests: write

问题管理

问题模板

在 .github/ISSUE_TEMPLATE/ 中创建模板：

缺陷报告：

---
name: Bug Report
about: Report a bug
labels: bug
---

## Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS:
- Browser:
- Version:

功能请求：

---
name: Feature Request
about: Suggest a new feature
labels: enhancement
---

## Problem
Describe the problem this feature would solve.

## Proposed Solution
Describe your proposed solution.

## Alternatives Considered
Other approaches you've considered.

标签

使用统一的标签：

• bug、enhancement、documentation
• good first issue、help wanted
• priority: high、priority: medium、priority: low
• status: in progress、status: blocked

仓库管理

分支保护规则

为 main 分支配置：

• 要求审查拉取请求
• 要求状态检查通过
• 要求解决所有对话
• 要求提交签名（可选）
• 限制强制推送

CODEOWNERS 文件

# .github/CODEOWNERS
* @default-team
/docs/ @docs-team
/src/api/ @backend-team
*.js @frontend-team

安全最佳实践

1. 启用安全功能

   • Dependabot 警报和更新
   • 使用 CodeQL 进行代码扫描
   • 机密扫描

2. 妥善管理机密

   • 使用仓库或组织机密
   • 定期轮换机密
   • 切勿将机密提交到代码中

3. 访问控制

   • 使用团队管理权限
   • 遵循最小权限原则
   • 定期审计访问权限

自动化建议

Dependabot 自动合并

name: Dependabot auto-merge
on: pull_request

permissions:
  contents: write
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]'
    steps:
      - name: Auto-merge minor updates
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

发布自动化

使用 semantic-release 或 release-please，根据约定式提交自动发布。