stand-ci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CI/CD Standards

CI/CD标准

Standards for CI/CD pipelines and GitHub Actions.

CI/CD流水线与GitHub Actions的规范标准。

GitHub Actions / Workflows

GitHub Actions / 工作流

Shell script code should NOT be inline in Actions/Workflow YAML files
Extract scripts to dedicated
```
.sh
```
or
```
.py
```
files in a
```
scripts/
```
directory
Reference these scripts from the workflow
ALWAYS pin actions to full commit SHAs, NOT version tags

Shell脚本代码不能内嵌在Actions/工作流YAML文件中
将脚本提取到
```
scripts/
```
目录下的专用
```
.sh
```
或
```
.py
```
文件中
在工作流中引用这些脚本
始终将actions固定到完整的提交SHA值，而非版本标签

Action Pinning

Action固定

Actions MUST be pinned to SHA hashes for security and reproducibility:

yaml

undefined

为了安全性和可复现性，Actions必须固定到SHA哈希值：

yaml

undefined

WRONG - version tag (can be moved, vulnerable to supply chain attacks)

错误示例 - 使用版本标签（可被篡改，易受供应链攻击）

uses: actions/checkout@v4
uses: actions/setup-python@v5

uses: actions/checkout@v4
uses: actions/setup-python@v5

CORRECT - pinned to SHA (immutable, secure)

正确示例 - 固定到SHA值（不可变，安全）

uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0

undefined

uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0

undefined

Finding SHAs

查找SHA值

Go to the action's releases page
Click on the version tag
Copy the full commit SHA
Add version as comment for readability

进入该action的发布页面
点击版本标签
复制完整的提交SHA值
添加版本作为注释以提升可读性

Why

为什么要遵循这些规范

Easier to test scripts locally
Better syntax highlighting and linting
Reusable across workflows
Cleaner workflow files
Proper version control diffs

便于在本地测试脚本
更好的语法高亮与代码检查
可在多个工作流中复用
工作流文件更简洁清晰
版本控制的差异对比更准确

Examples

示例

yaml

undefined

yaml

undefined

WRONG - inline script in workflow

错误示例 - 工作流中内嵌脚本

jobs: build: steps: - name: Build and deploy run: | echo "Building..." npm install npm run build if [ -f dist/index.js ]; then aws s3 sync dist/ s3://bucket/ fi

CORRECT - reference external script

正确示例 - 引用外部脚本

jobs: build: steps: - name: Build and deploy run: ./scripts/ci/build-and-deploy.sh

undefined

jobs: build: steps: - name: Build and deploy run: ./scripts/ci/build-and-deploy.sh

undefined

Script Organization

脚本组织

text

scripts/
└── ci/
    ├── build.sh
    ├── deploy.sh
    ├── test.sh
    └── utils/
        └── helpers.py

text

scripts/
└── ci/
    ├── build.sh
    ├── deploy.sh
    ├── test.sh
    └── utils/
        └── helpers.py

Script Requirements

脚本要求

Scripts must be executable (
```
chmod +x
```
)

Include shebang line (

#!/usr/bin/env bash

#!/usr/bin/env python3

)

Follow shell script best practices (set -euo pipefail for bash)

脚本必须具备可执行权限（
```
chmod +x
```
）

包含shebang行（

#!/usr/bin/env bash

或

#!/usr/bin/env python3

）

遵循Shell脚本最佳实践（bash脚本设置
```
set -euo pipefail
```
）

No Hand-Maintained Mirrors of Canonical Sources

不要手动维护标准源的镜像

If CI needs to verify that two files agree on the same value, the second file is a derived artifact — generate it, don't validate it.

Replace
```
verify-X-sync.py
```
scripts with
```
generate-X.py
```
; CI runs the generator with
```
--check
```
(exit 1 + unified diff on drift) instead of parsing both files and comparing.
The same generator runs locally for the writer flow and in CI for the gate flow — a single code path, no parser duplication.
Generators consumed by automation (e.g. Renovate
```
postUpgradeTasks
```
) should be stdlib-only so they run in any minimal container without dep installation.
Treat automation hooks as convenience, not correctness. The
```
--check
```
gate is the truth-keeper; if the hook silently fails, CI still catches the drift.

yaml

undefined

如果CI需要验证两个文件的值一致，第二个文件应作为派生产物——生成它，而非验证它。

用
```
generate-X.py
```
替换
```
verify-X-sync.py
```
脚本；CI运行生成器时使用
```
--check
```
参数（若存在差异则退出码为1并输出统一差异），而非解析两个文件进行对比。
同一个生成器既用于本地编写流程，也用于CI校验流程——单一代码路径，无需重复编写解析逻辑。
供自动化工具（如Renovate的
```
postUpgradeTasks
```
）使用的生成器应仅依赖标准库，以便在任何极简容器中运行，无需安装依赖。
将自动化钩子视为便利工具，而非正确性保障。
```
--check
```
校验是最终的真理守护者；若钩子静默失败，CI仍能检测到差异。

yaml

undefined

WRONG — verify two files agree

错误示例 — 验证两个文件是否一致

run: python3 scripts/ci/verify-manifest-sync.py
run: python3 scripts/ci/verify-tool-version-sync.py

run: python3 scripts/ci/verify-manifest-sync.py
run: python3 scripts/ci/verify-tool-version-sync.py

CORRECT — single generator, single check

正确示例 — 单一生成器，单一校验

run: python3 scripts/ci/generate-tool-versions.py --check

undefined

run: python3 scripts/ci/generate-tool-versions.py --check

undefined