Skip to content

Commit 37f9bef

Browse files
docs-botdocs-bot
authored
Merge pull request #44694 from github/repo-sync
Repo sync
2 parents 038aa7c + fb07809 commit 37f9bef

28 files changed

Lines changed: 1623 additions & 16 deletions

‎content/copilot/concepts/agents/about-github-agentic-workflows.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: About GitHub Agentic Workflows
3+
shortTitle: Agentic Workflows
4+
intro: 'Automate repetitive repository work with natural language instructions executed by AI coding agents in {% data variables.product.prodname_actions %}.'
5+
versions:
6+
feature: copilot
7+
contentType: concepts
8+
category:
9+
- Learn about Copilot
10+
---
11+
12+
{% data reusables.copilot.agentic-workflows-preview-note %}
13+
14+
## About {% data variables.copilot.agentic_workflows_short %}
15+
16+
{% data variables.copilot.github_agentic_workflows %} are AI-powered repository automations that you define in markdown and run as {% data variables.product.prodname_actions %} workflows. Unlike traditional automation with fixed if-then rules, {% data variables.copilot.agentic_workflows_short %} use coding agents to understand context, make decisions, and take meaningful actions—all from natural language instructions.
17+
18+
In practice, compared with traditional workflows that execute predefined steps:
19+
20+
* {% data variables.copilot.agentic_workflows_short_cap %} execute natural language instructions with contextual reasoning.
21+
* You still define guardrails in frontmatter, such as triggers, permissions, and safe outputs.
22+
23+
With {% data variables.copilot.agentic_workflows_short %}, you can automate tasks like:
24+
25+
* Triaging incoming issues and labeling them by type and priority
26+
* Investigating CI failures and suggesting fixes
27+
* Generating daily or weekly repository status reports
28+
* Keeping documentation up to date with code changes
29+
* Improving test coverage
30+
31+
## Benefits of using {% data variables.copilot.agentic_workflows_short %}
32+
33+
* **Automate repetitive repository work**. Define issue triage, CI investigation, documentation updates, and reporting in natural language.
34+
* **Reduce workflow complexity**. Write markdown instructions instead of building complex procedural scripts for every scenario.
35+
* **Keep human review in the loop**. {% data variables.copilot.agentic_workflows_short_cap %} can generate ready-to-review outputs, such as issues, comments, and pull requests, while you control approvals and merges.
36+
* **Run agents with layered security**. Agents run in firewalled containers with read-only tokens by default. Write actions are limited to declared "safe outputs" that you have defined, and checked by agentic threat detection.
37+
38+
## Requirements
39+
40+
To create and use {% data variables.copilot.agentic_workflows_short %}, you need:
41+
42+
* {% data variables.product.prodname_actions %} enabled for your repository.
43+
* An account with an AI engine (agent), such as {% data variables.product.prodname_copilot %}, {% data variables.product.prodname_anthropic_claude %}, {% data variables.product.prodname_openai_codex %}, or Google Gemini.
44+
* {% data variables.product.prodname_cli %} installed and authenticated
45+
46+
## How {% data variables.copilot.agentic_workflows_short %} work
47+
48+
Each workflow markdown file has two parts:
49+
50+
* **Frontmatter** (YAML between `---` markers): Configures when the workflow runs, what permissions it has, and what write operations are allowed.
51+
* **Markdown body**: Contains your natural language instructions that the AI agent follows.
52+
53+
At a high level, the process to create and use {% data variables.copilot.agentic_workflows_short %} is:
54+
55+
1. Define the agentic workflow `.md` file, including YAML frontmatter and markdown instructions.
56+
1. Compile the markdown workflow file into a hardened `.lock.yml` {% data variables.product.prodname_actions %} workflow file.
57+
1. Commit and push both files to the default branch of your repository.
58+
1. Run the workflow like any other {% data variables.product.prodname_actions %} workflow, on a trigger or in the {% data variables.product.github %} web interface for your repository. You can also run it from the {% data variables.product.prodname_cli %}.
59+
60+
Here's an example of a workflow to create a daily status report issue for a repository:
61+
62+
```markdown
63+
---
64+
on: daily
65+
66+
permissions:
67+
contents: read
68+
issues: read
69+
pull-requests: read
70+
copilot-requests: write
71+
72+
network: defaults
73+
74+
tools:
75+
github:
76+
toolsets: [default]
77+
78+
safe-outputs:
79+
create-issue:
80+
81+
---
82+
83+
# Daily Repo Status Report
84+
85+
Review recent activity in the repository, including issues, pull requests, discussions, and code changes.
86+
87+
Create a {% data variables.product.github %} issue summarizing what changed in the last 24 hours (merged pull requests, closed issues, and new discussions), any blockers or open questions mentioned in comments, progress toward visible goals, and recommended next steps for maintainers.
88+
89+
Keep the summary concise. Adjust the level of detail based on how much activity occurred.
90+
```
91+
92+
For detailed steps on creating and updating {% data variables.copilot.agentic_workflows_short %}, see [AUTOTITLE](/copilot/how-tos/github-agentic-workflows/creating-github-agentic-workflows).
93+
94+
## Supported coding agents
95+
96+
{% data variables.copilot.github_agentic_workflows %} support multiple coding agents, including:
97+
98+
* {% data variables.product.prodname_copilot %} (requires a {% data variables.product.prodname_copilot %} plan)
99+
* {% data variables.product.prodname_anthropic_claude %}
100+
* {% data variables.product.prodname_openai_codex %}
101+
* Google Gemini
102+
103+
You specify which agent to use in the workflow frontmatter property `engine`. Each engine requires its own authentication secret configured in your repository. {% data variables.product.prodname_copilot %} is the default engine if none is specified.
104+
105+
For more information, see the [engine reference](https://github.github.com/gh-aw/reference/engines/).
106+
107+
## Security guardrails
108+
109+
{% data variables.copilot.github_agentic_workflows %} are designed with security as a priority:
110+
111+
* **Read-only by default**: Workflows have read-only repository permissions unless you explicitly grant more.
112+
* **Safe outputs**: Write operations (such as creating issues, adding comments, or opening pull requests) are only allowed through validated `safe-outputs` declared in the frontmatter.
113+
* **Secrets stay outside the agent runtime**: Sensitive credentials are kept in isolated downstream jobs instead of being exposed directly to the agent.
114+
* **Threat detection**: Proposed outputs are scanned for suspicious or unsafe changes before write actions are applied.
115+
* **Firewalled execution**: Agents run in isolated {% data variables.product.prodname_actions %} environments.
116+
* **Role-based access**: You can restrict who can trigger or modify {% data variables.copilot.agentic_workflows_short %} using role-based access controls.
117+
118+
For a full architecture walkthrough, see the [security documentation](https://github.github.com/gh-aw/introduction/architecture/).
119+
120+
## Usage and billing
121+
122+
The total cost of {% data variables.copilot.agentic_workflows_short %} has two parts:
123+
124+
* {% data variables.product.prodname_actions %} minutes consumed by workflow jobs.
125+
* Inference costs from the configured AI engine.
126+
127+
For inference, {% data variables.copilot.github_agentic_workflows %} use AI Credits (AIC) as a general metric for monitoring and budgeting across engines. `1 AIC = $0.01 USD`.
128+
129+
How billing applies depends on the engine:
130+
131+
* Default {% data variables.product.prodname_copilot %} engine: AIC usage maps to {% data variables.product.prodname_ai_credits_short %} in {% data variables.product.prodname_copilot %} billing.
132+
* Third-party engine: Inference is billed by that provider.
133+
134+
You can use the {% data variables.product.prodname_cli %} to review usage and estimated cost for {% data variables.copilot.agentic_workflows_short %}. Use `gh aw logs` to view recent workflow runs, including duration, token usage, and AIC estimates across runs. Use `gh aw audit RUN-ID` to inspect a single run in more detail, including token usage and estimated inference cost. AIC values are best-effort estimates and may not exactly match provider invoices, so verify final charges in your provider's billing dashboard.
135+
136+
You can also set `max-ai-credits` in workflow frontmatter to cap inference usage for a single run. The default cap is 1,000 AIC per run.
137+
138+
For an overview of billing for {% data variables.copilot.github_agentic_workflows %} and cost optimization guidance, see [Cost management](https://github.github.com/gh-aw/reference/cost-management/) on the {% data variables.copilot.github_agentic_workflows %} documentation site.
139+
140+
### Enabling organization billing for {% data variables.copilot.github_agentic_workflows %}
141+
142+
For {% data variables.product.prodname_copilot %} agentic workflows in organization-owned repositories, if the organization has a {% data variables.product.prodname_copilot %} plan, we strongly recommend using {% data variables.product.prodname_actions %}' built-in `GITHUB_TOKEN`. This approach bills to the organization and avoids using a {% data variables.product.pat_generic %}.
143+
144+
To bill to the organization, you need:
145+
146+
1. An organization administrator to enable "Copilot CLI" and "Allow use of Copilot CLI billed to the organization" in {% data variables.product.prodname_copilot %} policy settings. If "Copilot CLI" is already enabled, the billing policy is enabled by default.
147+
1. In each workflow frontmatter, include `copilot-requests: write` under the `permissions` object.
148+
149+
When `copilot-requests: write` is set in workflow frontmatter permissions, the {% data variables.product.prodname_actions %}' token is used for Copilot requests, so you don't need a `COPILOT_GITHUB_TOKEN`. If the {% data variables.product.prodname_actions %} token does not have {% data variables.product.prodname_copilot %} access from the organization, the workflow fails when it sends Copilot requests, and you should configure `COPILOT_GITHUB_TOKEN` instead.
150+
151+
For detailed setup instructions, see [Using the built-in `GITHUB_TOKEN`](/copilot/how-tos/github-agentic-workflows/creating-github-agentic-workflows#using-the-built-in-github_token).
152+
153+
## Next steps
154+
155+
* To add your first agentic workflow, see [AUTOTITLE](/copilot/how-tos/github-agentic-workflows/quickstart).
156+
* For more information on creating and using {% data variables.copilot.agentic_workflows_short %}, see [AUTOTITLE](/copilot/how-tos/github-agentic-workflows/creating-github-agentic-workflows).
157+
* For the full reference documentation, including advanced patterns and examples, see the [{% data variables.copilot.github_agentic_workflows %} documentation site](https://github.github.com/gh-aw/).

‎content/copilot/concepts/agents/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ children:
1010
- /copilot-cli
1111
- /github-copilot-app
1212
- /code-review
13+
- /about-github-agentic-workflows
1314
- /copilot-memory
1415
- /hooks
1516
- /about-enterprise-plugin-standards

0 commit comments

Comments
 (0)