github-actions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Actions Code Review Rules

GitHub Actions 代码审查规则

Security (Critical)

安全（关键）

Pin actions to full commit SHA (not
```
@v1
```
or
```
@main
```
)
Use minimal
```
permissions
```
block (principle of least privilege)
Never echo secrets or use them in URLs
Use
```
secrets.GITHUB_TOKEN
```
instead of PATs when possible
Audit third-party actions before use
Review expressions (
```
${{ }}
```
) for injection risks; never interpolate untrusted user input
Validate all inputs to reusable workflows and custom actions

将 actions 固定到完整的提交 SHA（而非
```
@v1
```
或
```
@main
```
）
使用最小化的
```
permissions
```
块（最小权限原则）
切勿输出 secrets 或将其用于 URL 中
尽可能使用
```
secrets.GITHUB_TOKEN
```
而非 PATs
使用第三方 actions 前先进行审计
检查表达式（
```
${{ }}
```
）的注入风险；切勿插入不可信的用户输入
验证可复用工作流和自定义 actions 的所有输入

Permissions

权限设置

yaml

permissions:
  contents: read  # Minimal by default
  # Add only what's needed:
  # pull-requests: write
  # issues: write

yaml

permissions:
  contents: read  # Minimal by default
  # Add only what's needed:
  # pull-requests: write
  # issues: write

Secrets

密钥管理

Store secrets in repository/organization secrets
Use environments for production secrets with approvals
Don't pass secrets as command arguments (visible in logs)
Mask sensitive output with
```
::add-mask::
```
Never write secrets to files or artifacts (can be exposed)
Avoid passing secrets via environment variables unless absolutely required
Secrets in env vars can be visible in process listings

将密钥存储在仓库/组织的 secrets 中
对生产环境密钥使用带审批流程的环境配置
切勿将密钥作为命令参数传递（会在日志中可见）
使用
```
::add-mask::
```
屏蔽敏感输出
切勿将密钥写入文件或制品（可能会泄露）
除非绝对必要，否则避免通过环境变量传递密钥
环境变量中的密钥可能会在进程列表中暴露

Performance

性能优化

Use caching for dependencies (
```
actions/cache
```
or built-in)
Run independent jobs in parallel
Use
```
concurrency
```
to cancel redundant runs
Consider self-hosted runners for heavy workloads

对依赖项使用缓存（
```
actions/cache
```
或内置缓存功能）
并行运行独立的任务
使用
```
concurrency
```
取消冗余的运行
对于繁重的工作负载，考虑使用自托管运行器

Workflow Structure

工作流结构

Use reusable workflows for common patterns
Use composite actions for shared steps
Set appropriate
```
timeout-minutes
```
to prevent hung jobs
Use
```
if:
```
conditions to skip unnecessary jobs
Separate CI (testing), CD (deployments), and PR checks into distinct workflows
Use environments to distinguish between dev, staging, and production
Avoid mixing all concerns in a single monolithic workflow

对通用模式使用可复用工作流
对共享步骤使用复合 actions
设置合适的
```
timeout-minutes
```
以防止任务挂起
使用
```
if:
```
条件跳过不必要的任务
将CI（测试）、CD（部署）和PR检查拆分为独立的工作流
使用环境来区分开发、预发布和生产环境
避免将所有关注点混在一个单一的大型工作流中

Triggers

触发器

Be specific with
```
paths
```
and
```
branches
```
filters
Use
```
workflow_dispatch
```
for manual triggers
Consider
```
pull_request_target
```
security implications

明确设置
```
paths
```
和
```
branches
```
过滤器
使用
```
workflow_dispatch
```
进行手动触发
考虑
```
pull_request_target
```
的安全影响

Common Anti-patterns

常见反模式

Avoid

actions/checkout

with

persist-credentials: true

unless needed

Avoid running on
```
push
```
to all branches
Avoid hardcoding versions that need updates

除非必要，否则避免使用带有
```
persist-credentials: true
```
的
```
actions/checkout
```
避免在所有分支的
```
push
```
事件上运行
避免硬编码需要更新的版本

Action Updates and Maintenance

Action 更新与维护

Monitor pinned action SHAs for security fixes
Subscribe to security advisories for actions you use
Update actions regularly to get new features and fixes
Document why specific SHAs are pinned (security, stability)
Consider using Dependabot for action version updates

监控已固定的 action SHA 是否有安全修复
订阅你所使用的 actions 的安全公告
定期更新 actions 以获取新功能和修复
记录固定特定 SHA 的原因（安全、稳定性）
考虑使用 Dependabot 进行 action 版本更新

Testing and Validation

测试与验证

Lint workflows with tools like
```
actionlint
```
Test complex workflows in feature branches before merging
Validate workflow syntax before committing
Use workflow templates for consistency
Add job-level tests for workflow logic validation

使用
```
actionlint
```
等工具对工作流进行代码检查
在合并前，在特性分支中测试复杂工作流
提交前验证工作流语法
使用工作流模板以保持一致性
添加任务级测试以验证工作流逻辑

Error Handling

错误处理

Use
```
continue-on-error: false
```
as default (explicit failure)
Set
```
fail-fast: true
```
for matrix jobs to stop on first failure
Only use
```
continue-on-error: true
```
when failure is acceptable
Provide clear error messages in job outputs
Use status checks to ensure critical jobs pass

默认使用
```
continue-on-error: false
```
（显式失败）
对于矩阵任务，设置
```
fail-fast: true
```
以在首次失败时停止
仅当失败可接受时使用
```
continue-on-error: true
```
在任务输出中提供清晰的错误信息
使用状态检查确保关键任务通过

Documentation

文档

Add inline comments for complex workflow logic
Document workflow purpose and triggers
Maintain workflow README or documentation
Explain environment variables and their usage
Document required secret names and their purpose (never include actual secret values)

为复杂的工作流逻辑添加内联注释
记录工作流的用途和触发器
维护工作流的 README 或文档
说明环境变量及其用法
记录所需的密钥名称及其用途（切勿包含实际的密钥值）