gh-aw 并发与限流配置：用 concurrency 字段防止 AI 工作流重复执行的完整指南

gh-aw 并发与限流配置用 concurrency 字段防止 AI 工作流重复执行的完整指南【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows是一个把 AI 代理嵌入 GitHub Actions 的工作流框架你用 Markdown YAML frontmatter 定义 AI 自动化任务gh aw compile把它编译成标准的 GitHub Actions 工作流。而concurrency字段正是它的防重复执行开关——配合限流字段可以彻底避免 AI 任务重复跑、并发爆炸和费用失控。为什么需要 concurrency 并发控制AI 工作流的执行成本远高于普通 CI一次运行可能消耗数十分钟和可观的 API 额度。如果没有并发控制会出现三类典型问题问题表现后果重复触发连续 push / 连续评论触发多个运行同一任务被 AI 执行多遍重复创建 Issue、重复评论并发爆炸工作流自身 dispatch 更多工作流指数级增长配额瞬间耗尽陈旧运行新提交推上去后旧的分析仍在跑结果基于过时代码互相覆盖concurrency字段就是解决它们的钥匙。先理解gh-aw 内置的两层并发控制即使你不写任何concurrency配置gh-aw 编译器也会自动生成双层并发策略详见 pkg/workflow/concurrency.go1️⃣ 工作流层Per-Workflow按触发类型自动生成不同粒度的分组例如Issue 触发 → 按 Issue 编号分组同一 Issue 的运行互斥PR 触发 → 按 PR 编号分组且默认开启cancel-in-progress新提交自动取消过时运行Push 触发 → 按分支github.ref分组定时/其他 → 整个工作流一个分组并默认附加queue: max排队2️⃣ 引擎层Per-Engine默认生成gh-aw-{engine-id}这样的分组保证所有工作流共用同一个 AI 引擎时同一时刻只跑一个代理任务防止 AI 资源耗尽。 简单说不同 Issue/PR/分支之间可以并行但同一对象内串行、同一引擎全局串行。大多数场景下这套默认策略就够用了。concurrency 字段的两种写法在 frontmatter 中concurrency支持字符串和对象两种格式完整字段说明见 frontmatter-full.md字符串形式一行搞定基础隔离concurrency: my-task-${{ github.ref }}同一分支上同一时刻只跑一个其他运行排队等待。适合每个分支独立、分支内串行的最常见需求。对象形式精细控制取消与排队concurrency: group: my-task-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true # 新运行启动时取消正在运行的旧任务 queue: max # 排队策略single(默认) 或 max job-discriminator: ${{ github.run_id }} # gh-aw 扩展字段各子字段的作用group分组名支持 GitHub Actions 表达式动态生成。相同分组不能同时运行。cancel-in-progress设为true时只有最新一次有意义如 PR 分析场景新提交让旧结果失效。⚠️ 注意它不能与queue: max同时使用编译器会在编译期直接报错拦截见 concurrency_validation.go。queuesingle默认只保留最新一个待运行或max最多 100 个待运行按到达顺序排队。gh-aw 编译器生成的分组默认输出queue: max让连续触发如快速连续 push按序执行而不是丢弃。job-discriminatorgh-aw 扩展字段用于扇出fan-out场景——同一工作流被并发多次调用、输入不同时它给每个运行生成唯一的作业级分组避免旧运行被新运行误取消。该字段只在编译期生效不会出现在最终生成的 YAML 中。三个高频配置场景速查场景推荐配置要点PR 分析新提交让旧结果失效用默认值或cancel-in-progress: truePR 触发默认已开启取消无需额外配置定时报告不丢任何一次queue: max全部排队按序执行一个都不丢同一工作流并发多实例扇出job-discriminator: ${{ inputs.item_id }}每个输入独立分组互不干扰如需独立控制输出任务的并发比如避免重复创建 Issue还可以给safe-outputs作业单独配置concurrency-groupsafe-outputs: concurrency-group: safe-outputs-${{ github.repository }} create-issue:concurrency 之外配套限流字段防失控并发控制管同时跑几个限流字段管一段时间内跑几次。gh-aw 提供了多层防线user-rate-limit按用户限流防止单人高频触发user-rate-limit: max-runs-per-window: 5 # 每窗口最多 5 次1-10 window: 60 # 时间窗口分钟默认 60最大 180max-daily-ai-credits每日 AI 费用护栏滚动 24 小时内超过阈值默认 5000 AIC ≈ $50后新运行直接失败人工手动触发不受影响。safe-outputs的max限制如assign-to-agent默认最多 1 次防止代理再派生代理的指数级增长。timeout-minutesstop-after分别限制单次作业时长和工作流总存活时间。一个组合示例五层防线一次配齐engine: id: copilot timeout-minutes: 60 stop-after: 2h user-rate-limit: max-runs-per-window: 5 window: 60 max-daily-ai-credits: 5000常见问题排查运行立即被取消检查是否误开了cancel-in-progress: true或被用户限流触发——查看 pre-activation 日志即可确认。连续触发时旧运行被丢弃默认queue: single会丢弃旧的待运行改成queue: max即可全部排队。扇出调用后只剩最后一次在跑加job-discriminator让每次调用拥有独立分组。编译报错 queue: max cannot be combined with cancel-in-progress: true二选一需要取消就去掉queue: max需要全排队就改cancel-in-progress: false。延伸阅读并发控制完整参考docs/src/content/docs/reference/concurrency.md限流与防失控机制docs/src/content/docs/reference/rate-limiting-controls.md并发分组生成逻辑源码pkg/workflow/concurrency.go分组表达式编译期校验pkg/workflow/concurrency_validation.go一句话总结大多数场景直接用 gh-aw 的默认并发策略即可当你遇到结果会过时的场景就加cancel-in-progress遇到一次都不能丢的场景就用queue: max遇到多实例并发就加job-discriminator再叠加user-rate-limit和max-daily-ai-credits限流AI 工作流就能既高效又可控地跑起来。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考