github-agentic-workflows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Agentic Workflows

Procedures

流程

Step 1: Identify the repository state

Inspect the workspace for
```
.github/workflows/
```
,
```
.github/agents/
```
, existing
```
.lock.yml
```
files, and any
```
gh aw
```
usage.

Execute

node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs .

when a Node runtime is available.

Run
```
gh aw version
```
before making compiler-sensitive decisions so the workflow authoring path matches the installed CLI behavior.
If the repository contains multiple candidate workflows, prefer the workflow the user named or the one closest to the active issue, pull request, or automation surface.
If the repository has no GH-AW setup and the task is to create or maintain agentic workflows, read
```
references/authoring.md
```
before editing.
If the task is limited to standard deterministic GitHub Actions YAML without agentic markdown workflows, stop and explain that this skill does not apply.

Step 2: Choose the working mode

Classify the task as one of: repository setup, new workflow authoring, workflow revision, workflow installation from another repository, security review, or failure debugging.
Read
```
references/examples.md
```
when the task needs a starting pattern for scheduled reports, issue or PR triage, orchestration, or agent handoff.
Read
```
references/security-and-operations.md
```
when the workflow needs safe outputs, network policy, authentication, lockdown, threat detection, or run observability.
Read
```
references/troubleshooting.md
```
when the workflow fails to compile, install, authenticate, execute safe outputs, or access tools.

Step 3: Author or revise the workflow source

Keep the workflow source of truth in
```
.github/workflows/<workflow-name>.md
```
.
Use
```
assets/workflow.template.md
```
as the base shape when creating a new workflow.
Choose the smallest viable trigger surface and repository role scope that satisfies the task.
Keep
```
permissions:
```
read-only unless the workflow truly needs broader GitHub Actions permissions outside the agentic section.
Prefer
```
safe-outputs:
```
for comments, issues, labels, PRs, agent assignment, and orchestration instead of granting direct write access to the agent.
In safe-output workflows, instruct the agent to call
```
noop
```
when no action is required.
Keep
```
tools:
```
and
```
toolsets:
```
minimal and specific to the task.
Default to
```
engine: copilot
```
unless the task explicitly requires another engine and the repository is already prepared for that engine's authentication model.
Configure
```
network:
```
with least privilege. Prefer ecosystem identifiers such as
```
node
```
,
```
python
```
, or
```
github
```
over individual registry domains when the compiler supports them.
If strict mode and the installed CLI reject custom domains that the workflow still needs, prefetch external sources in deterministic setup steps and pass local files into the agent instead of broadly relaxing the firewall.
Do not rely on
```
${{ steps.<id>.outputs.* }}
```
placeholders reaching the agent-visible markdown body in real runs. If prompt instructions depend on runtime values, write them into a deterministic local file during setup and tell the agent to read that file.
Use imported or reusable workflows only when the repository genuinely benefits from shared logic or orchestration.
For recurring work across a dynamic set of inputs, prefer a reusable GH-AW worker plus a deterministic YAML wrapper for discovery and matrix fan-out.
When a reusable GH-AW worker is called from a matrix, do not leave it on the default shared workflow-level concurrency group. Set an explicit concurrency group keyed by the matrix input or prompt identity so parallel legs are not cancelled by GitHub's one-running-one-pending concurrency behavior.
Recompile the workflow after frontmatter, imports, or other compile-time configuration changes.
If only the markdown body changed and the workflow is edited directly on GitHub.com, do not recompile solely for body text changes.
Treat
```
.github/aw/
```
as transient GH-AW runtime and compiler scratch space during local compile, validate, or trial flows unless the workflow intentionally uses checked-in files from that path.

Step 4: Configure repository prerequisites and authentication

Read
```
references/authoring.md
```
before first-time repository setup.
Run
```
gh aw init
```
when the repository is not configured for GH-AW authoring and the user wants persistent setup.

Configure engine secrets with

gh aw secrets bootstrap

gh aw secrets set

Use
```
COPILOT_GITHUB_TOKEN
```
for Copilot engine authentication.
For Copilot runs, use a fine-grained PAT in
```
COPILOT_GITHUB_TOKEN
```
; a general
```
gho_...
```
OAuth token may pass secret checks but still fail real Copilot execution.
When using
```
gh aw trial
```
, verify that the host repository also has the required engine secret. Secrets from the logical or source repository are not copied automatically into the temporary or reusable host repo.
Re-check
```
gh aw version
```
after extension upgrades or reinstall paths so the repository guidance and compiler behavior stay aligned.
If a deterministic wrapper calls a reusable worker, make the caller workflow permissions at least as broad as the nested worker's requested
```
actions
```
,
```
contents
```
, and
```
pull-requests
```
scopes or the run can fail before agent execution starts.
Use a GitHub App or custom GitHub token when the workflow needs cross-repository reads or writes, Projects access, remote GitHub tool mode, or advanced safe outputs.
If the repository is public and the workflow will inspect untrusted external content, preserve lockdown and approval controls unless the task is explicitly a low-risk public workflow.

Step 5: Validate, compile, and execute

Run
```
gh aw fix --write
```
when the workflow uses deprecated fields or the compiler points to codemod-able drift.
Run
```
gh aw validate --strict
```
before treating a workflow as ready.
When the CLI version changed or a workflow depends on newer frontmatter behavior, run
```
gh aw compile --verbose
```
so warnings and generated-version changes are visible.
Run
```
gh aw compile
```
after validation succeeds and commit both the
```
.md
```
source and the generated
```
.lock.yml
```
file.
Use
```
gh aw run <workflow> --dry-run
```
to validate remote dispatch behavior, especially when you suspect branch, trigger, or workflow-discovery problems.
Use
```
gh aw trial ./.github/workflows/<workflow>.md
```
when you need to execute a local workflow source before pushing it. The explicit
```
./
```
path matters; without it, the CLI may parse the argument as a repository spec instead of a local file.
Use
```
gh aw run <workflow>
```
for direct execution only after the workflow source or lockfile actually exists on the target branch.
Use
```
gh aw status
```
,
```
gh aw logs
```
,
```
gh aw audit
```
, and
```
gh aw health
```
to review state, failures, cost, tool usage, and success trends after changes.

Step 6: Operate and improve professionally

Review whether the workflow can be simplified, split into smaller workflows, or converted into shared components.
Prefer staged safe outputs for initial rollout of workflows that create issues, comments, or pull requests at scale.
For recurring maintenance, pin or review the installed
```
gh-aw
```
version deliberately and update workflows through
```
gh aw update
```
or
```
gh aw upgrade
```
instead of ad hoc copy-paste.
Keep workflow prompts specific, bounded, and auditable. Move broad strategy into reusable imports or agent files when multiple workflows need the same rules.

步骤1：识别仓库状态

检查工作区是否存在
```
.github/workflows/
```
、
```
.github/agents/
```
、已有的
```
.lock.yml
```
文件，以及任何
```
gh aw
```
使用痕迹。

当有可用Node运行时，执行

node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs .

。

在做出编译器相关的敏感决策前运行
```
gh aw version
```
，确保工作流创作路径与已安装的CLI行为匹配。
如果仓库包含多个候选工作流，优先选择用户指定的工作流，或者与活跃issue、拉取请求、自动化场景最接近的工作流。
如果仓库没有GH-AW配置，且任务是创建或维护Agentic工作流，编辑前请阅读
```
references/authoring.md
```
。
如果任务仅限于处理不带Agentic markdown工作流的标准确定性GitHub Actions YAML，请停止并说明本技能不适用。

步骤2：选择工作模式

将任务归类为以下类型之一：仓库初始化、新工作流创作、工作流修订、从其他仓库安装工作流、安全审查、故障调试。
当任务需要定时报表、issue/PR分类、编排、Agent交接的参考模板时，阅读
```
references/examples.md
```
。
当工作流需要配置安全输出、网络策略、身份验证、权限锁定、威胁检测、运行可观测性时，阅读
```
references/security-and-operations.md
```
。
当工作流出现编译失败、安装失败、身份验证失败、安全输出执行失败、工具访问失败时，阅读
```
references/troubleshooting.md
```
。

步骤3：创作或修订工作流源码

将工作流唯一源码存储在
```
.github/workflows/<workflow-name>.md
```
中。
创建新工作流时，使用
```
assets/workflow.template.md
```
作为基础模板。
选择满足任务需求的最小触发范围和仓库角色权限 scope。
保持
```
permissions:
```
为只读，除非工作流确实需要Agentic部分之外的更广泛GitHub Actions权限。
评论、issue、标签、PR、Agent分配、编排场景优先使用
```
safe-outputs:
```
，不要直接为Agent授予写权限。
在使用安全输出的工作流中，指示Agent在无需执行操作时调用
```
noop
```
。
保持
```
tools:
```
和
```
toolsets:
```
最小化，仅包含任务所需的特定工具。
默认使用
```
engine: copilot
```
，除非任务明确要求其他引擎，且仓库已经配置好对应引擎的身份验证模式。
按最小权限原则配置
```
network:
```
，编译器支持的情况下优先使用
```
node
```
、
```
python
```
、
```
github
```
这类生态标识符，而非单独的 registry 域名。
如果严格模式和已安装的CLI拒绝了工作流所需的自定义域名，请在确定性的设置步骤中预取外部资源，将本地文件传入Agent，不要直接大范围放宽防火墙限制。
不要依赖
```
${{ steps.<id>.outputs.* }}
```
占位符在实际运行时传递到Agent可见的markdown正文中。如果提示词指令依赖运行时变量，请在设置步骤中将其写入确定性的本地文件，告知Agent读取该文件即可。
仅当仓库确实能从共享逻辑或编排中获益时，才使用导入或可复用工作流。
对于动态输入集的 recurring 任务，优先使用可复用GH-AW worker加确定性YAML封装的方式实现发现和矩阵展开。
从矩阵中调用可复用GH-AW worker时，不要使用默认的共享工作流级别并发组。设置显式的并发组，以矩阵输入或提示词标识作为key，避免并行任务被GitHub的“一个运行中一个待处理”并发规则取消。
修改frontmatter、导入配置或其他编译时配置后，重新编译工作流。
如果仅修改了markdown正文，且是直接在GitHub.com上编辑工作流，不需要仅为正文修改重新编译。
将
```
.github/aw/
```
视为本地编译、验证、试运行流程中的临时GH-AW运行时和编译器暂存空间，除非工作流有意使用该路径下的提交文件。

步骤4：配置仓库前置依赖和身份验证

首次配置仓库前阅读
```
references/authoring.md
```
。
如果仓库未配置GH-AW创作环境，且用户需要持久化配置，运行
```
gh aw init
```
。

使用

gh aw secrets bootstrap

或

gh aw secrets set

配置引擎密钥。

Copilot引擎身份验证使用
```
COPILOT_GITHUB_TOKEN
```
。
Copilot运行时，在
```
COPILOT_GITHUB_TOKEN
```
中使用细粒度PAT；通用的
```
gho_...
```
OAuth token可能通过密钥校验，但在实际Copilot执行时仍会失败。
使用
```
gh aw trial
```
时，确认宿主仓库也配置了所需的引擎密钥。逻辑仓库或源仓库的密钥不会自动复制到临时或可复用宿主仓库中。
扩展升级或重新安装后重新检查
```
gh aw version
```
，确保仓库指南和编译器行为保持一致。
如果确定性封装调用了可复用worker，请确保调用方工作流的权限至少不低于嵌套worker请求的
```
actions
```
、
```
contents
```
、
```
pull-requests
```
scope，否则运行会在Agent执行前失败。
当工作流需要跨仓库读写、Projects访问、远程GitHub工具模式、高级安全输出时，使用GitHub App或自定义GitHub token。
如果是公共仓库，且工作流会检查不受信任的外部内容，请保留锁定和审批控制，除非任务明确是低风险公共工作流。

步骤5：验证、编译、执行

当工作流使用了已弃用字段，或者编译器提示存在可自动迁移的配置偏差时，运行
```
gh aw fix --write
```
。
确认工作流就绪前，运行
```
gh aw validate --strict
```
。
当CLI版本变更，或者工作流依赖更新的frontmatter特性时，运行
```
gh aw compile --verbose
```
，以便查看警告和生成版本变更。
验证通过后运行
```
gh aw compile
```
，同时提交
```
.md
```
源码和生成的
```
.lock.yml
```
文件。
使用
```
gh aw run <workflow> --dry-run
```
验证远程触发行为，尤其是当你怀疑存在分支、触发规则、工作流发现问题时。
需要在推送前执行本地工作流源码时，使用
```
gh aw trial ./.github/workflows/<workflow>.md
```
。显式的
```
./
```
路径非常重要；没有该前缀时，CLI可能会将参数解析为仓库规格而非本地文件。
仅当工作流源码或lockfile确实存在于目标分支上时，才使用
```
gh aw run <workflow>
```
直接执行。
变更后使用
```
gh aw status
```
、
```
gh aw logs
```
、
```
gh aw audit
```
、
```
gh aw health
```
查看状态、故障、成本、工具使用情况和成功率趋势。

步骤6：专业运维与优化

评估工作流是否可以简化、拆分为更小的工作流，或者转换为共享组件。
首次上线大规模创建issue、评论、PR的工作流时，优先使用分阶段安全输出模式。
日常维护时，有意识地固定或审查已安装的
```
gh-aw
```
版本，通过
```
gh aw update
```
或
```
gh aw upgrade
```
更新工作流，不要随意复制粘贴。
保持工作流提示词明确、范围可控、可审计。如果多个工作流需要相同的规则，将通用策略迁移到可复用导入或Agent文件中。

Error Handling

错误处理

gh extension install github/gh-aw

fails, use the standalone installer path documented in

references/troubleshooting.md

If compilation fails, fix frontmatter syntax, deprecated fields, imports, or permission mismatches before continuing.
If compiler behavior does not match the docs you are reading, trust the installed
```
gh aw version
```
and validate against that version before rewriting the workflow shape.
If
```
gh aw trial
```
rejects
```
.github/workflows/<name>.md
```
as an invalid repository spec, retry with an explicit local path such as
```
./.github/workflows/<name>.md
```
.
If a reusable worker succeeds in isolation but the wrapper run fails at startup, inspect caller-workflow
```
permissions:
```
inheritance before changing the worker logic.
If a matrix of reusable GH-AW workers cancels most legs immediately, inspect the called workflow's concurrency group first. A shared workflow-level group will cancel pending legs even when
```
cancel-in-progress
```
is
```
false
```
.
If a trial run fails on the activation step with
```
Validate COPILOT_GITHUB_TOKEN secret
```
, inspect the host repository with
```
gh secret list -R <host-repo>
```
. The source repository's secrets are not inherited by the trial host.
If
```
gh aw trial --force-delete-host-repo-before
```
fails, confirm you have admin rights on the host repository and that the current GitHub auth token includes
```
delete_repo
```
scope.
If the workflow prompt still shows unresolved runtime placeholders during execution, move those values into a generated local context file and have the agent read that file explicitly.
If local
```
gh aw compile
```
,
```
gh aw validate
```
, or
```
gh aw trial
```
commands create
```
.github/aw/
```
files such as
```
actions-lock.json
```
or logs, treat them as transient byproducts and remove them before commit unless the repository intentionally keeps them.
If safe outputs do nothing, verify that staged mode is intentional and that the prompt explicitly instructs the agent to call
```
noop
```
when no write action is needed.
If
```
gh aw mcp inspect
```
fails on a compiled scheduled workflow source with a fuzzy schedule parsing error, treat that as an inspection-path limitation first. Re-run
```
gh aw compile
```
, prefer installed-workflow or run-log based debugging, and do not assume the workflow itself is invalid if validation and compile already passed.
If the compiler rejects engine fields or tool entries that look valid from older examples, trust the installed schema. In
```
gh aw v0.58.3
```
,
```
engine.max-turns
```
is not supported for Copilot,
```
bash
```
must be
```
true
```
,
```
false
```
, or an allowlist, and bare
```
edit:
```
/
```
web-fetch:
```
keys are accepted where boolean values are not.
If URLs are sanitized as
```
(redacted)
```
or tools cannot reach required services, tighten and expand
```
network.allowed
```
deliberately rather than disabling the firewall.
If Copilot inference fails with a configured token, verify that the PAT owner actually has Copilot license and inference access.
If public-repository workflows miss external contributor content, confirm whether GitHub lockdown mode is blocking that content before changing workflow logic.

如果

gh extension install github/gh-aw

失败，使用

references/troubleshooting.md

中记录的独立安装路径。

如果编译失败，先修复frontmatter语法、弃用字段、导入配置、权限不匹配问题再继续。
如果编译器行为与你阅读的文档不一致，请以已安装的
```
gh aw version
```
为准，重写工作流结构前先对照该版本验证。
如果
```
gh aw trial
```
将
```
.github/workflows/<name>.md
```
判定为无效仓库规格，使用显式本地路径重试，例如
```
./.github/workflows/<name>.md
```
。
如果可复用worker单独运行成功，但封装调用在启动时失败，修改worker逻辑前先检查调用方工作流的
```
permissions:
```
继承配置。
如果可复用GH-AW worker矩阵的大多数任务立即被取消，先检查被调用工作流的并发组配置。即使
```
cancel-in-progress
```
设为
```
false
```
，共享工作流级别的并发组也会取消待处理的任务。
如果试运行在激活步骤失败，提示
```
Validate COPILOT_GITHUB_TOKEN secret
```
，使用
```
gh secret list -R <host-repo>
```
检查宿主仓库配置。源仓库的密钥不会被试运行宿主继承。
如果
```
gh aw trial --force-delete-host-repo-before
```
失败，确认你对宿主仓库有管理员权限，且当前GitHub认证token包含
```
delete_repo
```
scope。
如果工作流提示词在执行时仍存在未解析的运行时占位符，将这些值移动到生成的本地上下文文件中，让Agent显式读取该文件。
如果本地
```
gh aw compile
```
、
```
gh aw validate
```
、
```
gh aw trial
```
命令生成了
```
.github/aw/
```
下的文件，例如
```
actions-lock.json
```
或日志，除非仓库有意保留这些文件，否则将其视为临时副产品，提交前删除。
如果安全输出没有执行任何操作，确认分阶段模式是否是预期配置，且提示词明确指示Agent在无需写操作时调用
```
noop
```
。
如果
```
gh aw mcp inspect
```
检查已编译的定时工作流源码时出现模糊定时解析错误，优先视为检查路径限制。重新运行
```
gh aw compile
```
，优先使用已安装工作流或运行日志调试，如果验证和编译已经通过，不要默认认为工作流本身无效。
如果编译器拒绝了旧示例中看起来有效的引擎字段或工具条目，以已安装的schema为准。在
```
gh aw v0.58.3
```
中，Copilot不支持
```
engine.max-turns
```
，
```
bash
```
的值必须为
```
true
```
、
```
false
```
或允许列表，不需要布尔值的场景下可以直接使用裸
```
edit:
```
/
```
web-fetch:
```
键。
如果URL被清理为
```
(redacted)
```
，或者工具无法访问所需服务，要有针对性地收紧或扩展
```
network.allowed
```
配置，不要直接禁用防火墙。
如果配置了token的情况下Copilot推理失败，确认PAT所属用户确实有Copilot许可证和推理访问权限。
如果公共仓库工作流无法获取外部贡献者内容，修改工作流逻辑前先确认是否是GitHub锁定模式阻止了该内容。