Skip to content

Commit d07932e

Browse files
dsymedsyme
committed
tweak FAQ
1 parent 3cd0311 commit d07932e

1 file changed

Lines changed: 103 additions & 91 deletions

File tree

  • docs/src/content/docs/reference

‎docs/src/content/docs/reference/faq.md‎

Lines changed: 103 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,6 @@ Your first call should be reliable, deterministic CI/CD. If you use agentic work
2222

2323
## Capabilities
2424

25-
### Can I edit workflows directly on GitHub.com without recompiling?
26-
27-
Yes! The **markdown body** (AI instructions) is loaded at runtime and can be edited directly on GitHub.com or in any editor. Changes take effect on the next workflow run without recompilation.
28-
29-
However, **frontmatter configuration** (tools, permissions, triggers, network rules) is embedded in the compiled workflow and requires recompilation when changed. Run `gh aw compile my-workflow` after editing frontmatter.
30-
31-
See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed.
32-
3325
### What's the difference between agentic workflows and regular GitHub Actions workflows?
3426

3527
Agentic workflows use AI to interpret natural language instructions in markdown instead of complex YAML. The AI engine can call pre-approved tools to perform tasks while running with read-only default permissions, safe outputs, and sandboxed execution.
@@ -65,6 +57,75 @@ See [MultiRepoOps](/gh-aw/patterns/multirepoops/) for coordinating across reposi
6557

6658
Yes, and in many cases we recommend it. Private repositories are ideal for proprietary code, creating a "sidecar" repository with limited access, testing workflows, and organization-internal automation. See [SideRepoOps](/gh-aw/patterns/siderepoops/) for patterns using private repositories.
6759

60+
### Can I edit workflows directly on GitHub.com without recompiling?
61+
62+
Yes! The **markdown body** (AI instructions) is loaded at runtime and can be edited directly on GitHub.com or in any editor. Changes take effect on the next workflow run without recompilation.
63+
64+
However, **frontmatter configuration** (tools, permissions, triggers, network rules) is embedded in the compiled workflow and requires recompilation when changed. Run `gh aw compile my-workflow` after editing frontmatter.
65+
66+
See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed.
67+
68+
### Can workflows trigger other workflows?
69+
70+
Yes, using the `dispatch-workflow` safe output:
71+
72+
```yaml wrap
73+
safe-outputs:
74+
dispatch-workflow:
75+
max: 1
76+
```
77+
78+
This allows your workflow to trigger up to 1 other workflows with custom inputs. See [Safe Outputs](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) for details.
79+
80+
### Can I use MCP servers with agentic workflows?
81+
82+
Yes! [Model Context Protocol (MCP)](/gh-aw/reference/glossary/#mcp-model-context-protocol) servers extend workflow capabilities with custom tools and integrations. Configure them in your frontmatter:
83+
84+
```yaml wrap
85+
tools:
86+
mcp-servers:
87+
my-server:
88+
image: "ghcr.io/org/my-mcp-server:latest"
89+
network:
90+
allowed: ["api.example.com"]
91+
```
92+
93+
See [Getting Started with MCP](/gh-aw/guides/getting-started-mcp/) and [MCP Servers](/gh-aw/guides/mcps/) for configuration guides.
94+
95+
### Can workflows be broken up into shareable components?
96+
97+
Workflows can import shared configurations and components:
98+
99+
```yaml wrap
100+
imports:
101+
- shared/github-tools.md
102+
- githubnext/agentics/shared/common-tools.md
103+
```
104+
105+
This enables reusable tool configurations, network settings, and permissions across workflows. See [Imports](/gh-aw/reference/imports/) and [Packaging Imports](/gh-aw/guides/packaging-imports/) for details.
106+
107+
### Can I run workflows on a schedule?
108+
109+
Yes, use cron expressions in the `on:` trigger:
110+
111+
```yaml wrap
112+
on:
113+
schedule:
114+
- cron: "0 9 * * MON" # Every Monday at 9am UTC
115+
```
116+
117+
See [Schedule Syntax](/gh-aw/reference/schedule-syntax/) for cron expression reference.
118+
119+
### Can I run workflows conditionally?
120+
121+
Yes, use the `if:` expression at the workflow level:
122+
123+
```yaml wrap
124+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
125+
```
126+
127+
See [Conditional Execution](/gh-aw/reference/frontmatter/#conditional-execution-if) in the Frontmatter Reference for details.
128+
68129
## Guardrails
69130

70131
### Agentic workflows run in GitHub Actions. Can they access my repository secrets?
@@ -118,41 +179,22 @@ network:
118179

119180
See [Network Permissions](/gh-aw/reference/network/) for complete configuration options.
120181

121-
## Costs & Usage
122-
123-
### Who pays for the use of AI?
124-
125-
This depends on the AI engine (coding agent) you use:
126-
127-
- **GitHub Copilot CLI** (default): Usage is currently associated with the individual GitHub account of the user supplying the COPILOT_GITHUB_TOKEN, and is drawn from the monthly quota of premium requests for that account. See [GitHub Copilot billing](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot).
128-
- **Claude**: Usage is billed to the Anthropic account associated with ANTHROPIC_API_KEY Actions secret in the repository.
129-
- **Codex**: Usage is billed to your OpenAI account associated with OPENAI_API_KEY Actions secret in the repository.
130-
131-
### What's the approximate cost per workflow run?
132-
133-
Costs vary depending on workflow complexity, AI model, and execution time. GitHub Copilot CLI uses 1-2 premium requests per workflow execution with agentic processing. Track usage with `gh aw logs` for runs and metrics, `gh aw audit <run-id>` for detailed token usage and costs, or check your AI provider's usage portal. Consider creating separate PAT/API keys per repository for tracking.
134-
135-
Reduce costs by optimizing prompts, using smaller models, limiting tool calls, reducing run frequency, and caching results.
182+
## Configuration & Setup
136183

137-
### Can I change the model being used, e.g., use a cheaper or more advanced one?
184+
### What is a workflow lock file?
138185

139-
Yes! You can configure the model in your workflow frontmatter:
186+
A **workflow lock file** (`.lock.yml`) is a traditional GitHub Actions workflow generated for your workflow markdown file (`.md`). It basically contains scaffolding and guardrails around a coding agent that is going to execute your workflow prompting in GitHub Actions. When you run `gh aw compile`, the lock file will appear or update and contain a complete GitHub Actions YAML file with all guradrail hardening applied.
140187

141-
```yaml wrap
142-
engine:
143-
id: copilot
144-
model: gpt-5 # or claude-sonnet-4
145-
```
188+
Both files should be committed to version control:
146189

147-
Or switch to a different engine entirely:
190+
- **`.md` file**: Your source file - easy to read, edit, and understand
191+
- **`.lock.yml` file**: The lock file - what GitHub Actions actually runs
148192

149-
```yaml wrap
150-
engine: claude
151-
```
193+
The lock file contains SHA-pinned actions, resolved imports, configured permissions, and all the infrastructure needed for secure execution. You can inspect it to see exactly what will run - there's no hidden configuration.
152194

153-
See [AI Engines](/gh-aw/reference/engines/) for all configuration options.
195+
The naming convention (`.lock.yml`) reflects that this file "locks in" the exact workflow configuration at compile time, ensuring reproducibility and auditability. If you modify the frontmatter in your `.md` file, you must recompile to update the lock file.
154196

155-
## Configuration & Setup
197+
When the workflow runs, the prompt itself is taken from the markdown file at runtime, so you can edit the markdown without recompiling and see changes in the next run. However, any changes to frontmatter (permissions, tools, triggers) require recompilation to update the lock file.
156198

157199
### Why do I need a token or key?
158200

@@ -166,6 +208,14 @@ The executing agentic workflow uses your nominated coding agent (defaulting to G
166208

167209
If you want to use a coding agent that isn't currently supported (Copilot, Claude, or Codex), you can use the custom engine to define your own GitHub Actions steps, contribute support to the [gh-aw repository](https://github.com/github/gh-aw), or open an issue describing your use case. See [AI Engines](/gh-aw/reference/engines/).
168210

211+
### Can I test workflows without affecting my repository?
212+
213+
Yes! Use [TrialOps](/gh-aw/patterns/trialops/) to test workflows in isolated trial repositories. This lets you validate behavior and iterate on prompts without creating real issues, PRs, or comments in your actual repository.
214+
215+
### Where can I find help with common issues?
216+
217+
See [Common Issues](/gh-aw/troubleshooting/common-issues/) for detailed troubleshooting guidance including workflow failures, debugging strategies, permission issues, and network problems.
218+
169219
## Workflow Design
170220

171221
### Should I focus on one workflow, or write many different ones?
@@ -180,75 +230,37 @@ Either approach works well. AI-assisted authoring using `/agent agentic-workflow
180230

181231
Yes, for the purpose of this technology. An **"agent"** is an agentic workflow in a repository - an AI-powered automation that can reason, make decisions, and take actions. We use **"agentic workflow"** as it's plainer and emphasizes the workflow nature of the automation, but the terms are synonymous in this context.
182232

183-
## Troubleshooting
184-
185-
### Where can I find help with common issues?
186-
187-
See [Common Issues](/gh-aw/troubleshooting/common-issues/) for detailed troubleshooting guidance including workflow failures, debugging strategies, permission issues, and network problems.
188-
189-
### Can I test workflows without affecting my repository?
190-
191-
Yes! Use [TrialOps](/gh-aw/patterns/trialops/) to test workflows in isolated trial repositories. This lets you validate behavior and iterate on prompts without creating real issues, PRs, or comments in your actual repository.
192-
193-
## Advanced Topics
194-
195-
### Can workflows trigger other workflows?
196-
197-
Yes, using the `dispatch-workflow` safe output:
233+
## Costs & Usage
198234

199-
```yaml wrap
200-
safe-outputs:
201-
dispatch-workflow:
202-
max: 1
203-
```
235+
### Who pays for the use of AI?
204236

205-
This allows your workflow to trigger up to 1 other workflows with custom inputs. See [Safe Outputs](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) for details.
237+
This depends on the AI engine (coding agent) you use:
206238

207-
### Can I use MCP servers with agentic workflows?
239+
- **GitHub Copilot CLI** (default): Usage is currently associated with the individual GitHub account of the user supplying the COPILOT_GITHUB_TOKEN, and is drawn from the monthly quota of premium requests for that account. See [GitHub Copilot billing](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot).
240+
- **Claude**: Usage is billed to the Anthropic account associated with ANTHROPIC_API_KEY Actions secret in the repository.
241+
- **Codex**: Usage is billed to your OpenAI account associated with OPENAI_API_KEY Actions secret in the repository.
208242

209-
Yes! [Model Context Protocol (MCP)](/gh-aw/reference/glossary/#mcp-model-context-protocol) servers extend workflow capabilities with custom tools and integrations. Configure them in your frontmatter:
243+
### What's the approximate cost per workflow run?
210244

211-
```yaml wrap
212-
tools:
213-
mcp-servers:
214-
my-server:
215-
image: "ghcr.io/org/my-mcp-server:latest"
216-
network:
217-
allowed: ["api.example.com"]
218-
```
245+
Costs vary depending on workflow complexity, AI model, and execution time. GitHub Copilot CLI uses 1-2 premium requests per workflow execution with agentic processing. Track usage with `gh aw logs` for runs and metrics, `gh aw audit <run-id>` for detailed token usage and costs, or check your AI provider's usage portal. Consider creating separate PAT/API keys per repository for tracking.
219246

220-
See [Getting Started with MCP](/gh-aw/guides/getting-started-mcp/) and [MCP Servers](/gh-aw/guides/mcps/) for configuration guides.
247+
Reduce costs by optimizing prompts, using smaller models, limiting tool calls, reducing run frequency, and caching results.
221248

222-
### Can workflows be broken up into shareable components?
249+
### Can I change the model being used, e.g., use a cheaper or more advanced one?
223250

224-
Workflows can import shared configurations and components:
251+
Yes! You can configure the model in your workflow frontmatter:
225252

226253
```yaml wrap
227-
imports:
228-
- shared/github-tools.md
229-
- githubnext/agentics/shared/common-tools.md
254+
engine:
255+
id: copilot
256+
model: gpt-5 # or claude-sonnet-4
230257
```
231258

232-
This enables reusable tool configurations, network settings, and permissions across workflows. See [Imports](/gh-aw/reference/imports/) and [Packaging Imports](/gh-aw/guides/packaging-imports/) for details.
233-
234-
### Can I run workflows on a schedule?
235-
236-
Yes, use cron expressions in the `on:` trigger:
259+
Or switch to a different engine entirely:
237260

238261
```yaml wrap
239-
on:
240-
schedule:
241-
- cron: "0 9 * * MON" # Every Monday at 9am UTC
262+
engine: claude
242263
```
243264

244-
See [Schedule Syntax](/gh-aw/reference/schedule-syntax/) for cron expression reference.
245-
246-
### Can I run workflows conditionally?
247-
248-
Yes, use the `if:` expression at the workflow level:
249-
250-
```yaml wrap
251-
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
252-
```
265+
See [AI Engines](/gh-aw/reference/engines/) for all configuration options.
253266

254-
See [Conditional Execution](/gh-aw/reference/frontmatter/#conditional-execution-if) in the Frontmatter Reference for details.

0 commit comments

Comments
 (0)