act-workflow-syntax

用途

该技能在创建或修改 GitHub Actions 工作流文件（.github/workflows/*.yml）时使用，覆盖工作流结构、触发器、作业、步骤，以及同时兼容 GitHub 与本地 act 运行的最佳实践。

工作流文件结构

每个 GitHub Actions 工作流遵循以下基本结构：

name: Workflow Name
user-invocable: false
on: [push, pull_request]  # 触发器

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Commands here"

顶层字段包括：name（可读的工作流名称，可选但推荐）、on（触发事件，如 push、pull_request、workflow_dispatch 等）、env（对所有作业可用的环境变量）、jobs（作业定义映射）、permissions（工作流的令牌权限）。

工作流触发器

支持单个事件、多个事件、带过滤条件的事件（指定分支、路径、类型），以及手动触发（workflow_dispatch，可定义输入项、描述、是否必填、默认值与类型选项）和定时触发（schedule，按 cron 表达式）。

作业配置

作业可配置基础步骤、环境变量、依赖关系（通过 needs 指定前置作业）以及矩阵构建（strategy.matrix，可跨多个操作系统与 Node 版本组合，并支持 fail-fast: false）。

步骤

步骤可使用现成 Action（通过 uses，配合 with 传参，如 checkout、setup-node、upload-artifact），也可运行命令（run，支持单行、多行、命名、指定工作目录与 shell），并可通过 if 设置条件（如分支判断、success()、failure()、always()）。

表达式与上下文

可使用 github.event_name、github.ref_name、github.sha、github.actor、job.status、runner.os 等上下文，可通过 secrets 引用密钥，也可使用 contains、startsWith、endsWith、format 等函数。

Act 相关注意事项

可本地测试工作流：运行全部（act）、指定事件（act push）、指定作业（act -j build）、干跑校验（act --dryrun）、列出工作流（act -l）、指定平台（act -P ubuntu-latest=catthehacker/ubuntu:act-latest）。可通过判断 $ACT 环境变量区分运行环境。本地测试密钥可写入 .secrets 文件（act --secret-file .secrets）或逐个传入（act -s KEY=value）。

最佳实践

推荐：使用语义化作业与步骤名、固定 Action 版本、矩阵构建设 fail-fast: false、设置 timeout-minutes、使用 working-directory 而非 cd、推送前用 act --dryrun 本地测试、为依赖启用缓存、部署作业使用 environments。

不推荐：在工作流中硬编码密钥、Action 使用 latest 标签、每次文件变更都触发（应使用 path 过滤）、创建过度复杂的工作流、忽略 act 兼容性、忽略 YAML 语法校验。

常见模式

包括构建与测试（CI）、按标签部署（on.push.tags: 'v*'，通过 GITHUB_OUTPUT 输出版本号）、以及单仓库中按变更文件检测后分别构建（结合 dorny/paths-filter）。

技能介绍

用途