workflow-setup

工作流设置技能

设置用于持续集成和部署的 GitHub Actions 工作流。

适用场景

• 需要为新项目配置 CI/CD
• 为现有项目补充缺失的工作流
• 将工作流版本更新到最新版本
• 自动化测试和质量检查
• 设置部署流水线

不适用场景

• 已配置且为最新版本的 GitHub Actions 工作流
• 项目使用其他 CI 平台（GitLab CI、CircleCI 等）
• 项目未托管在 GitHub 上
• 更新现有工作流时，请改用 /attune:upgrade-project

标准工作流

Python 工作流

1. test.yml - 在推送或 PR 时运行 pytest
2. lint.yml - 运行 ruff lint 检查
3. typecheck.yml - 运行 mypy 类型检查
4. publish.yml - 在发布时发布到 PyPI

Rust 工作流

1. ci.yml - 集成测试、lint 和检查的工作流
2. release.yml - 构建并发布版本

TypeScript 工作流

1. test.yml - 运行 Jest 测试
2. lint.yml - 运行 ESLint
3. build.yml - 构建生产版本
4. deploy.yml - 部署到托管平台（Vercel、Netlify 等）

工作流

1. 检查现有工作流

ls -la .github/workflows/

验证： 使用 --help 标志运行命令，以验证其是否可用。

2. 确定缺失的工作流

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. 渲染工作流模板

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. 验证工作流

# Syntax check (requires act or gh CLI)
gh workflow list

# Or manually check YAML syntax
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/test.yml'))"

验证： 运行 pytest -v，以验证测试通过。

工作流最佳实践

使用最新版本的操作

# Good - pinned to major version
- uses: actions/checkout@v4
- uses: actions/setup-python@v5

# Avoid - unpinned or outdated
- uses: actions/checkout@v2
- uses: actions/setup-python@latest

验证： 运行 pytest -v，以验证测试通过。

矩阵测试（Python）

strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]
    os: [ubuntu-latest, macos-latest, windows-latest]

验证： 运行 pytest -v，以验证测试通过。

缓存依赖项

- uses: actions/setup-python@v5
  with:
    python-version: '3.10'
    cache: 'pip'  # Cache pip dependencies

验证： 运行 python --version，以验证 Python 环境。

工作流中的 Shell 脚本安全

在工作流中编写内联 Shell 脚本时，确保正确处理退出代码：

# BAD - pipeline masks exit code
- run: |
    make typecheck 2>&1 | grep -v "^make\["
    echo "Typecheck passed"  # Runs even if make failed!

# GOOD - use pipefail
- 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}

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

更新工作流

要将工作流更新到最新版本：

/attune:upgrade-project --component workflows

验证： 使用 --help 标志运行命令，以验证其是否可用。

相关技能

• Skill(attune:project-init) - 完整的项目初始化
• Skill(sanctum:pr-prep) - 准备 PR 并执行 CI 检查

退出条件

• 检测到的语言所需的所有工作流文件均存在于 .github/workflows/ 下 （Python：test.yml + lint.yml + typecheck.yml；Rust：ci.yml；TypeScript：test.yml + lint.yml + build.yml），且包含有效的 YAML 语法，并通过 python3 -c "import yaml; yaml.safe_load(open('...'))" 验证。
• gh workflow list 将每个已创建的工作流文件列为条目，确认 GitHub 能识别这些工作流定义。
• 工作流中的任何内联 Shell 脚本都使用 set -eo pipefail 或显式捕获退出代码；未启用 pipefail 的管道错误屏蔽（cmd | grep）会被标记为错误。
• 如果项目使用 GitHub Actions 以外的 CI 平台（GitLab CI、CircleCI），该技能会报告此不兼容情况并停止，而不是生成 GitHub 专用文件。