github-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Workflow Best Practices

GitHub工作流最佳实践

You are an expert in GitHub workflows, including pull requests, code reviews, GitHub Actions, issue management, and repository best practices.

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

Core Principles

核心原则

Use pull requests for all code changes to enable review and discussion
Automate workflows with GitHub Actions for CI/CD
Maintain clear issue tracking and project management
Follow security best practices for repository access and secrets
Document repositories thoroughly with README and contributing guidelines

所有代码变更均使用拉取请求，以便进行审查和讨论
借助GitHub Actions实现CI/CD工作流自动化
维护清晰的问题跟踪与项目管理
遵循仓库访问和密钥的安全最佳实践
利用README和贡献指南完善仓库文档

Pull Request Best Practices

拉取请求最佳实践

Creating Effective Pull Requests

创建高效的拉取请求

Keep PRs small and focused
- One feature or fix per PR
- Aim for under 400 lines of changes when possible
- Split large features into stacked PRs
Write descriptive PR titles
- Use conventional commit style:
```
feat: add user authentication
```
- Be specific about what the PR accomplishes

PR Description Template

markdown

## 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)

Link related issues
- Use
```
Closes #123
```
  or
```
Fixes #123
```
  to auto-close issues
- Reference related issues with
```
#123
```

保持PR精简且聚焦
- 每个PR对应一项功能或一个修复
- 尽可能将代码变更控制在400行以内
- 复杂功能拆分为分层PR（Stacked Pull Requests）
撰写描述性PR标题
- 使用约定式提交风格：
```
feat: add user authentication
```
- 明确说明PR实现的内容

PR描述模板

markdown

## 摘要
变更内容及动机的简要说明。

## 变更详情
- 具体变更内容的要点列表

## 测试情况
- 变更的测试方式
- 复现/验证步骤

## 关联问题
Closes #123

## 截图（如适用）

关联相关问题
- 使用
```
Closes #123
```
  或
```
Fixes #123
```
  自动关闭问题
- 用
```
#123
```
  引用相关问题

Stacked Pull Requests

分层拉取请求

For complex features, use stacked PRs:

Create a base feature branch
Create subsequent PRs that build on each other
Merge in order from base to top
Keep each PR small and reviewable

针对复杂功能，使用分层PR：

创建基础功能分支
创建基于前序分支的后续PR
按从基础到顶层的顺序合并
保持每个PR精简且便于审查

Code Review Guidelines

代码审查指南

As a Reviewer

作为审查者

Review promptly - Respond within 24 hours when possible
Be constructive - Focus on improvement, not criticism
Ask questions - Seek to understand before suggesting changes
Prioritize feedback:
- Blocking: Security issues, bugs, breaking changes
- Important: Performance, maintainability
- Nice-to-have: Style preferences, minor improvements

及时审查 - 尽可能在24小时内回复
保持建设性 - 聚焦改进而非批评
主动提问 - 先理解再建议变更
区分反馈优先级:
- 阻塞性：安全问题、漏洞、破坏性变更
- 重要：性能、可维护性
- 锦上添花：风格偏好、小改进

Comment Conventions

评论约定

Use prefixes to indicate comment severity:

```
blocking:
```
Must be addressed before merge
```
suggestion:
```
Recommended improvement
```
question:
```
Seeking clarification
```
nit:
```
Minor style or preference (optional to address)
```
praise:
```
Positive feedback on good code

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

```
blocking:
```
合并前必须解决
```
suggestion:
```
推荐的改进方向
```
question:
```
寻求澄清
```
nit:
```
微小的风格或偏好问题（可选择解决）
```
praise:
```
对优质代码的正面反馈

Example Review Comments

审查评论示例

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.

blocking: 该SQL查询存在注入风险。
请使用参数化查询。

suggestion: 考虑将此逻辑提取到单独的
函数中，提升可测试性。

nit: 此处建议使用`const`而非`let`，因为该值
不会被重新赋值。

Approval Criteria

批准标准

All blocking comments addressed
Tests pass
CI/CD checks pass
At least one approval from code owner

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

GitHub Actions

Workflow Best Practices

工作流最佳实践

Use workflow templates

yaml

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

Cache dependencies

yaml

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

Use reusable workflows

yaml

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

Set appropriate timeouts
yaml
```
jobs:
  build:
    timeout-minutes: 10
```

使用工作流模板

yaml

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

缓存依赖

yaml

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

使用可复用工作流

yaml

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

设置合理超时时间
yaml
```
jobs:
  build:
    timeout-minutes: 10
```

Security in Actions

Actions安全规范

Use
```
secrets
```
for sensitive data

Pin action versions with SHA:

uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29

Limit
```
GITHUB_TOKEN
```
permissions
Review third-party actions before use

yaml

permissions:
  contents: read
  pull-requests: write

使用
```
secrets
```
存储敏感数据

通过SHA固定Action版本：

uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29

限制
```
GITHUB_TOKEN
```
权限
使用第三方Action前进行审查

yaml

permissions:
  contents: read
  pull-requests: write

Issue Management

问题管理

Issue Templates

问题模板

Create

.github/ISSUE_TEMPLATE/

with templates:

Bug Report:

markdown

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

在

.github/ISSUE_TEMPLATE/

目录下创建模板：

Bug报告：

markdown

---
name: Bug Report
about: 提交Bug报告
labels: bug
---

Description

问题描述

Clear description of the bug.

Bug的清晰说明。

Steps to Reproduce

复现步骤

Step one
Step two

步骤一
步骤二

Expected Behavior

预期行为

What should happen.

应该出现的结果。

Actual Behavior

实际行为

What actually happens.

实际出现的结果。

Environment

环境信息

OS:
Browser:
Version:


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

操作系统：
浏览器：
版本：


**功能请求：**
```markdown
---
name: Feature Request
about: 建议新功能
labels: enhancement
---

Problem

问题背景

Describe the problem this feature would solve.

该功能要解决的问题。

Proposed Solution

解决方案建议

Describe your proposed solution.

您提出的解决方案。

Alternatives Considered

备选方案考虑

Other approaches you've considered.

undefined

您考虑过的其他实现方式。

undefined

Labels

标签规范

Use consistent labels:

```
bug
```
,
```
enhancement
```
,
```
documentation
```
```
good first issue
```
,
```
help wanted
```

priority: high

priority: medium

priority: low

```
status: in progress
```
,
```
status: blocked
```

使用统一的标签：

```
bug
```
、
```
enhancement
```
、
```
documentation
```
```
good first issue
```
、
```
help wanted
```

priority: high

、

priority: medium

、

priority: low

```
status: in progress
```
、
```
status: blocked
```

Repository Management

仓库管理

Branch Protection Rules

分支保护规则

Configure for main branch:

Require pull request reviews
Require status checks to pass
Require conversation resolution
Require signed commits (optional)
Restrict force pushes

为main分支配置以下规则：

要求拉取请求审查
要求状态检查通过
要求讨论已解决
要求提交签名（可选）
禁止强制推送

CODEOWNERS File

CODEOWNERS文件

undefined

undefined

.github/CODEOWNERS

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

undefined

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

undefined

Security Best Practices

安全最佳实践

Enable security features
- Dependabot alerts and updates
- Code scanning with CodeQL
- Secret scanning
Manage secrets properly
- Use repository or organization secrets
- Rotate secrets regularly
- Never commit secrets to code
Access control
- Use teams for permissions
- Follow principle of least privilege
- Audit access regularly

启用安全功能
- Dependabot告警与更新
- 借助CodeQL进行代码扫描
- 密钥扫描
妥善管理密钥
- 使用仓库或组织级密钥
- 定期轮换密钥
- 绝不将密钥提交到代码中
访问控制
- 通过团队分配权限
- 遵循最小权限原则
- 定期审计访问权限

Automation Recommendations

自动化建议

Auto-merge for Dependabot

Dependabot自动合并

yaml

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 }}

yaml

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 }}

Release Automation

发布自动化

Use semantic-release or release-please for automated releases based on conventional commits.

基于约定式提交，使用semantic-release或release-please实现自动化发布。