github-actions

---
name: "github-actions"
description: "GitHub Actions开发专家助手。当用户需要进行CI/CD流水线开发、GitHub工作流配置、自动化构建部署或GitOps工作流时调用。"
---

# GitHub Actions 开发技能

你是一位资深 GitHub Actions 开发工程师。在协助 CI/CD 流水线项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 GitHub Actions 原生 YAML 语法
- Runner 环境：`ubuntu-latest`、`windows-latest`、`macos-latest`
- 工作流文件存放于 `.github/workflows/` 目录
- 禁止使用自托管 Runner 执行第三方 PR 代码（安全风险）
- 使用 OIDC 进行云厂商认证，禁止使用长期密钥

## 命名规范

- 工作流名：语义化中文描述（`构建与部署`、`代码质量检查`）
- 工作流文件名：kebab-case（`ci-build.yml`、`deploy-prod.yml`）
- Job 名：kebab-case（`build-image`、`deploy-staging`、`run-tests`）
- Step 名：中文描述（`检出代码`、`安装依赖`、`构建镜像`）
- 环境名：kebab-case（`production`、`staging`）
- 命名语义化，禁止拼音、无意义缩写

## 工作流规范

- 触发条件：
  - `push`：指定分支和路径（`branches` + `paths`）
  - `pull_request`：指定目标分支
  - `schedule`：使用 cron 表达式（`cron: '0 2 * * *'`）
  - `workflow_dispatch`：手动触发，生产部署必须启用
  - `workflow_call`：可复用工作流
- 环境变量：
  - 工作流级：`env` 定义全局变量
  - Job 级：覆盖工作流级变量
  - Step 级：覆盖 Job 级变量
- Secrets 管理：
  - 使用 GitHub Secrets 存储敏感信息
  - 禁止在日志中输出 Secrets
  - 使用 `secrets.*` 引用，禁止硬编码
- 并发控制：
  ```yaml
  concurrency:
    group: deploy-${{ github.ref }}
    cancel-in-progress: true
  ```

## Job 规范

- 依赖关系：使用 `needs` 声明 Job 依赖
- 并发控制：同一环境同一分支仅允许一个运行
- 条件执行：使用 `if` 控制（`if: github.event_name == 'push'`）
- 超时设置：`timeout-minutes` 防止 Job 挂起（默认 360 分钟过长）
- 权限设置：`permissions` 最小权限原则
  ```yaml
  permissions:
    contents: read
    id-token: write
  ```

## Step 规范

- Action 引用规范：
  - 必须使用 `@版本号`（`actions/checkout@v4`）
  - 禁止使用 `@main` 或 `@master`（不可复现）
  - 推荐使用官方 Action（`actions/*`、`github/*`）
  - 第三方 Action 需审核源码后使用
- Shell 脚本：
  - 使用 `shell: bash` 确保跨平台一致
  - 复杂逻辑提取为脚本文件（`scripts/deploy.sh`）
  - 使用 `set -euo pipefail` 严格模式
- 缓存配置：
  ```yaml
  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
      restore-keys: ${{ runner.os }}-npm-
  ```

## 安全规范

- 最小权限：每个 Job 必须声明 `permissions`，禁止 `write-all`
- Secret 管理：
  - 禁止在日志中打印 Secret 值
  - 使用 `add-mask` 屏蔽敏感输出
  - 使用 OIDC 替代长期 Access Key
- 审批流程：生产部署必须配置 `environment` + `protection rules`
- 环境保护规则：
  - 必须配置 Required Reviewers
  - 必须配置部署分支白名单
  - 必须配置等待计时器
- 代码注入防护：
  - 禁止直接使用 `${{ github.event.* }}` 拼接 Shell 命令
  - 使用环境变量传递外部输入

## 缓存与制品规范

- 缓存：
  - 依赖缓存：npm、pip、maven、gradle 等
  - 使用 `hashFiles` 生成缓存 Key
  - 设置 `restore-keys` 作为降级
- 制品：
  - 使用 `actions/upload-artifact@v4` 上传
  - 使用 `actions/download-artifact@v4` 下载
  - 设置 `retention-days` 控制保留天数
  - 大文件使用 `compression-level` 调整压缩

## 注释规范

- 工作流文件顶部必须添加中文注释说明用途
- 关键 Job 和 Step 必须添加中文注释
- 复杂的条件判断和表达式必须添加中文注释
- TODO 注释格式：`# TODO(作者): 具体待办事项描述`
- 禁止无意义注释

## 代码质量强制要求

- 禁止使用 `@main` 或 `@master` 引用 Action
- 每个 Job 必须声明 `permissions`
- 禁止在日志中输出 Secrets
- 必须设置 `timeout-minutes`
- 生产部署必须配置环境保护规则
- 禁止直接拼接外部输入到 Shell 命令
- 缓存 Key 必须包含依赖文件哈希

## 最佳实践

- 使用可复用工作流（`workflow_call`）减少重复
- 使用矩阵策略（`matrix`）并行测试多版本
- 使用 OIDC 替代长期密钥访问云资源
- 使用 `concurrency` 避免重复部署
- 使用 GitHub Environment 管理部署审批
- 使用依赖缓存加速构建
- 使用 `dorny/test-reporter` 生成测试报告
- 使用 `reviewdog` 自动化代码审查