Back to Details

workflow-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Table of Contents

目录

Workflow Setup Skill

工作流搭建技能

Set up GitHub Actions workflows for continuous integration and deployment.
为持续集成与部署搭建GitHub Actions工作流。

When To Use

适用场景

  • Need CI/CD for a new project
  • Adding missing workflows to existing project
  • Updating workflow versions to latest
  • Automating testing and quality checks
  • Setting up deployment pipelines
  • 新项目需要CI/CD
  • 为现有项目补充缺失的工作流
  • 将工作流版本更新至最新
  • 自动化测试与质量检查
  • 搭建部署流水线

When NOT To Use

不适用场景

  • GitHub Actions workflows already configured and current
  • Project uses different CI platform (GitLab CI, CircleCI, etc.)
  • Not hosted on GitHub
  • Use 
    /attune:upgrade-project
    instead for updating existing workflows
  • 已配置并使用当前版本的GitHub Actions工作流
  • 项目使用其他CI平台（GitLab CI、CircleCI等）
  • 项目未托管在GitHub上
  • 更新现有工作流请使用
    /attune:upgrade-project

Standard Workflows

标准工作流

Python Workflows

Python工作流

  1. test.yml - Run pytest on push/PR
  2. lint.yml - Run ruff linting
  3. typecheck.yml - Run mypy type checking
  4. publish.yml - Publish to PyPI on release
  1. test.yml - 在推送/PR时运行pytest测试
  2. lint.yml - 运行ruff代码检查
  3. typecheck.yml - 运行mypy类型检查
  4. publish.yml - 在发布时推送至PyPI

Rust Workflows

Rust工作流

  1. ci.yml - Combined test/lint/check workflow
  2. release.yml - Build and publish releases
  1. ci.yml - 整合测试/代码检查/验证的工作流
  2. release.yml - 构建并发布版本

TypeScript Workflows

TypeScript工作流

  1. test.yml - Run Jest tests
  2. lint.yml - Run ESLint
  3. build.yml - Build for production
  4. deploy.yml - Deploy to hosting (Vercel, Netlify, etc.)
  1. test.yml - 运行Jest测试
  2. lint.yml - 运行ESLint代码检查
  3. build.yml - 构建生产环境版本
  4. deploy.yml - 部署至托管平台（Vercel、Netlify等）

Workflow

操作流程

1. Check Existing Workflows

1. 检查现有工作流

bash
ls -la .github/workflows/
Verification: Run the command with 
--help
flag to verify availability.
bash
ls -la .github/workflows/
验证方式： 加上
--help
参数运行命令，确认其可用。

2. Identify Missing Workflows

2. 识别缺失的工作流

python
from project_detector import ProjectDetector

detector = ProjectDetector(Path.cwd())
language = detector.detect_language()

required_workflows = {
    "python": ["test.yml", "lint.yml", "typecheck.yml"],
    "rust": ["ci.yml"],
    "typescript": ["test.yml", "lint.yml", "build.yml"],
}

missing = detector.get_missing_configurations(language)
Verification: Run 
pytest -v
to verify tests pass.
python
from project_detector import ProjectDetector

detector = ProjectDetector(Path.cwd())
language = detector.detect_language()

required_workflows = {
    "python": ["test.yml", "lint.yml", "typecheck.yml"],
    "rust": ["ci.yml"],
    "typescript": ["test.yml", "lint.yml", "build.yml"],
}

missing = detector.get_missing_configurations(language)
验证方式： 运行
pytest -v
确认测试通过。

3. Render Workflow Templates

3. 渲染工作流模板

python
workflows_dir = Path(".github/workflows")
workflows_dir.mkdir(parents=True, exist_ok=True)

for workflow in required_workflows[language]:
    template = templates_dir / language / "workflows" / f"{workflow}.template"
    output = workflows_dir / workflow

    engine.render_file(template, output)
    print(f"✓ Created: {output}")
Verification: Run the command with 
--help
flag to verify availability.
python
workflows_dir = Path(".github/workflows")
workflows_dir.mkdir(parents=True, exist_ok=True)

for workflow in required_workflows[language]:
    template = templates_dir / language / "workflows" / f"{workflow}.template"
    output = workflows_dir / workflow

    engine.render_file(template, output)
    print(f"✓ Created: {output}")
验证方式： 加上
--help
参数运行命令，确认其可用。

4. Validate Workflows

4. 验证工作流

bash
undefined
bash
undefined

Syntax check (requires act or gh CLI)

语法检查（需要act或gh CLI）

gh workflow list
gh workflow list

Or manually check YAML syntax

或手动检查YAML语法

python3 -c "import yaml; yaml.safe_load(open('.github/workflows/test.yml'))"
**Verification:** Run `pytest -v` to verify tests pass.
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/test.yml'))"
**验证方式：** 运行`pytest -v`确认测试通过。

Workflow Best Practices

工作流最佳实践

Use Latest Action Versions

使用最新Action版本

yaml
undefined
yaml
undefined

Good - pinned to major version

推荐 - 固定到主版本

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

Avoid - unpinned or outdated

避免 - 未固定或版本过时

  • uses: actions/checkout@v2
  • uses: actions/setup-python@latest
**Verification:** Run `pytest -v` to verify tests pass.
  • uses: actions/checkout@v2
  • uses: actions/setup-python@latest
**验证方式：** 运行`pytest -v`确认测试通过。

Matrix Testing (Python)

矩阵测试（Python）

yaml
strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]
    os: [ubuntu-latest, macos-latest, windows-latest]
Verification: Run 
pytest -v
to verify tests pass.
yaml
strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]
    os: [ubuntu-latest, macos-latest, windows-latest]
验证方式： 运行
pytest -v
确认测试通过。

Caching Dependencies

依赖缓存

yaml
- uses: actions/setup-python@v5
  with:
    python-version: '3.10'
    cache: 'pip'  # Cache pip dependencies
Verification: Run 
python --version
to verify Python environment.
yaml
- uses: actions/setup-python@v5
  with:
    python-version: '3.10'
    cache: 'pip'  # 缓存pip依赖
验证方式： 运行
python --version
确认Python环境正确。

Shell Script Safety in Workflows

工作流中的Shell脚本安全

When writing inline shell scripts in workflows, ensure proper exit code handling:
yaml
undefined
在工作流中编写内联Shell脚本时，需确保正确处理退出码：
yaml
undefined

BAD - pipeline masks exit code

错误示例 - 流水线会掩盖退出码

  • run: | make typecheck 2>&1 | grep -v "^make[" echo "Typecheck passed" # Runs even if make failed!
  • run: | make typecheck 2>&1 | grep -v "^make[" echo "Typecheck passed" # 即使make失败也会执行！

GOOD - use pipefail

正确示例 - 使用pipefail

  • run: | set -eo pipefail make typecheck 2>&1 | grep -v "^make["
  • run: | set -eo pipefail make typecheck 2>&1 | grep -v "^make["

GOOD - capture exit code explicitly

正确示例 - 显式捕获退出码

  • run: | output=$(make typecheck 2>&1) || exit_code=$? echo "$output" | grep -v "^make[" || true exit ${exit_code:-0}

For complex wrapper scripts, run `/pensive:shell-review` before integrating.
  • run: | output=$(make typecheck 2>&1) || exit_code=$? echo "$output" | grep -v "^make[" || true exit ${exit_code:-0}

对于复杂的包装脚本，集成前请运行`/pensive:shell-review`。

Updating Workflows

更新工作流

To update workflows to latest versions:
bash
/attune:upgrade-project --component workflows
Verification: Run the command with 
--help
flag to verify availability.
将工作流更新至最新版本：
bash
/attune:upgrade-project --component workflows
验证方式： 加上
--help
参数运行命令，确认其可用。

Related Skills

相关技能

  • Skill(attune:project-init)
    - Full project initialization
  • Skill(sanctum:pr-prep)
    - PR preparation with CI checks
  • Skill(attune:project-init)
    - 完整项目初始化
  • Skill(sanctum:pr-prep)
    - 包含CI检查的PR准备

Troubleshooting

故障排查

Common Issues

常见问题

Command not found Ensure all dependencies are installed and in PATH
Permission errors Check file permissions and run with appropriate privileges
Unexpected behavior Enable verbose logging with 
--verbose
flag
命令未找到 确保所有依赖已安装并在PATH中
权限错误 检查文件权限并使用适当权限运行
异常行为 添加
--verbose
参数启用详细日志