Skip to content

Commit eaa7d68

Browse files
dsymedsyme
authored
Merge branch 'main' into mossaka/docs
2 parents 4933911 + 889383c commit eaa7d68

16 files changed

Lines changed: 653 additions & 496 deletions

‎.github/workflows/test-claude.lock.yml‎

Lines changed: 9 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎DEVGUIDE.md‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
# Developer Guide
22

3-
> [!CAUTION]
4-
> This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
5-
6-
This guide provides comprehensive information for developers working on gh-aw, including setup, development workflow, testing, and contribution guidelines.
7-
83
## Development Environment Setup
94

105
### 1. Clone and Setup Repository

‎README.md‎

Lines changed: 12 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/).
44

5-
> [!CAUTION]
6-
> This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
5+
> [!WARNING]
6+
> This extension is a research demonstrator. It is in early development and may change significantly. Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.
77
88
## ⚡ Quick Start (30 seconds)
99

@@ -18,14 +18,7 @@ Now, add a weekly research report to your repo (this adds [this sample](https://
1818
```bash
1919
gh aw add weekly-research -r githubnext/agentics --pr
2020
```
21-
This command will create a PR to your repo adding several files including `.github/workflows/weekly-research.md` and `.github/workflows/weekly-research.lock.yml`:
22-
23-
```
24-
.github/
25-
└── workflows/
26-
├── weekly-research.md # Agentic Workflow
27-
└── weekly-research.lock.yml # Compiled GitHub Actions Workflow
28-
```
21+
This command will create a PR to your repo adding several files including `.github/workflows/weekly-research.md` and `.github/workflows/weekly-research.lock.yml`.
2922

3023
Your repository will also need an `ANTHROPIC_API_KEY` (for Anthropic Claude) or `OPENAI_API_KEY` (for OpenAI Codex) Actions secret set up to run workflows that use AI models. You can add this using one of the following commands:
3124

@@ -57,16 +50,12 @@ on:
5750

5851
permissions:
5952
contents: read # Minimal permissions for main job
53+
issues: write # Needed to add issue comments
6054

6155
tools:
6256
github:
6357
allowed: [add_issue_comment]
6458

65-
output:
66-
issue:
67-
title-prefix: "[triage] "
68-
labels: [automation, triage]
69-
7059
timeout_minutes: 5
7160
---
7261

@@ -75,18 +64,12 @@ timeout_minutes: 5
7564
Analyze issue #${{ github.event.issue.number }} and help with triage:
7665

7766
1. Read the issue content
78-
2. Post a helpful comment summarizing the issue
79-
3. Write your analysis to ${{ env.GITHUB_AW_OUTPUT }} for automatic issue creation
67+
2. Study the repository
68+
3. Post a helpful comment summarizing the issue
8069

8170
Keep responses concise and helpful.
8271
```
8372

84-
> **💡 Learn more**: For complete workflow configuration details, see the [Documentation](docs/index.md)
85-
86-
> **📚 Workflow commands**: See [Commands Documentation](docs/commands.md) for complete workflow management commands including `list`, `status`, `enable`, `disable`, and more.
87-
88-
> **🤖 Teach AI** how write agentic workflows with [custom instructions](docs/vscode.md#copilot-instructions).
89-
9073
## 📂 Available Demonstrator Workflows from "[The Agentics](https://github.com/githubnext/agentics?tab=readme-ov-file#-the-agentics)"
9174

9275
### Research & Planning Workflows
@@ -143,7 +126,7 @@ Adding an agentic workflow adds two main files, for example:
143126

144127
Both files are stored in `.github/workflows/` - the first file is the markdown file that defines the workflow, and the second is a lock file that contains the resolved workflow configuration to an actual GitHub Actions workflow.
145128

146-
### Updating after workflow edits
129+
### You're in control
147130

148131
You are in control of the workflow files in `.github/workflows/` and can adapt them to your needs. If you modify the markdown file, you can compile it to update the lock file:
149132

@@ -153,35 +136,15 @@ gh aw compile
153136

154137
You will see the changes reflected in the `.lock.yml` file, which is the actual workflow that will run on GitHub Actions. You should commit changes to both files to your repository.
155138

156-
### Configuring the agentic processor
139+
### Security of Agentic Workflows
157140

158-
By default Claude Code is used as the agentic processor. You can configure the agentic processor by editing the frontmatter of the markdown workflow files.
159-
160-
```markdown
161-
engine: claude # Default: Claude Code
162-
engine: codex # Experimental: OpenAI Codex CLI with MCP support
163-
```
164-
165-
You can also specify this on the command line when adding or running workflows:
166-
167-
```bash
168-
# Use Claude (default)
169-
gh aw add weekly-research --engine claude
170-
171-
# Use Codex (experimental)
172-
gh aw add weekly-research --engine codex
173-
```
174-
175-
This will override the `engine` setting in the frontmatter of the markdown file.
176-
177-
> **🔧 Advanced configuration**: For detailed information about permissions, tools, secrets, and all configuration options, see the [Documentation](docs/index.md)
141+
Security is a key consideration when using agentic workflows. Please see the [Security Notes](docs/security-notes.md) for guidelines related to workflow security and handling untrusted inputs.
178142

179-
## Security of Agentic Workflows
143+
> **💡 Learn more**: For complete workflow configuration details, see the [Documentation](docs/index.md)
180144
181-
Security is a key consideration when using agentic workflows. Please see the [Security Notes](docs/security-notes.md) for guidelines related to workflow security and handling untrusted inputs.
145+
> **📚 Workflow commands**: See [Commands Documentation](docs/commands.md) for complete workflow management commands including `list`, `status`, `enable`, `disable`, and more.
182146
183-
> [!CAUTION]
184-
> GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use.
147+
> **🤖 Teach AI** how write agentic workflows with [custom instructions](docs/vscode.md#copilot-instructions).
185148
186149
## 💬 Share Feedback
187150

‎docs/alias-triggers.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 🏷️ Alias Triggers
2+
3+
This guide covers alias triggers and context text functionality for agentic workflows.
4+
5+
## Special `alias:` Trigger
6+
7+
GitHub Agentic Workflows add the convenience `alias:` trigger to create workflows that respond to `@mentions` in issues and comments.
8+
9+
```yaml
10+
on:
11+
alias:
12+
name: my-bot # Optional: defaults to filename without .md extension
13+
```
14+
15+
This automatically creates:
16+
- Issue and PR triggers (`opened`, `edited`, `reopened`)
17+
- Comment triggers (`created`, `edited`)
18+
- Conditional execution matching `@alias-name` mentions
19+
20+
You can combine `alias:` with other events like `workflow_dispatch` or `schedule`:
21+
22+
```yaml
23+
on:
24+
alias:
25+
name: my-bot
26+
workflow_dispatch:
27+
schedule:
28+
- cron: "0 9 * * 1"
29+
```
30+
31+
**Note**: You cannot combine `alias` with `issues`, `issue_comment`, or `pull_request` as they would conflict.
32+
33+
**Note**: Using this feature results in the addition of `.github/actions/check-team-member/action.yml` file to the repository when the workflow is compiled. This file is used to check if the user triggering the workflow has appropriate permissions to operate in the repository.
34+
35+
### Example alias workflow
36+
37+
```markdown
38+
---
39+
on:
40+
alias:
41+
name: summarize-issue
42+
permissions:
43+
issues: write
44+
tools:
45+
github:
46+
allowed: [add_issue_comment]
47+
---
48+
49+
# Issue Summarizer
50+
51+
When someone mentions @summarize-issue in an issue or comment,
52+
analyze and provide a helpful summary.
53+
54+
The current context text is: "${{ needs.task.outputs.text }}"
55+
```
56+
57+
## Context Text (`needs.task.outputs.text`)
58+
59+
All workflows have access to a special computed `needs.task.outputs.text` value that provides context based on the triggering event:
60+
61+
```markdown
62+
# Analyze this content: "${{ needs.task.outputs.text }}"
63+
```
64+
65+
**How `text` is computed:**
66+
- **Issues**: `title + "\n\n" + body`
67+
- **Pull Requests**: `title + "\n\n" + body`
68+
- **Issue Comments**: `comment.body`
69+
- **PR Review Comments**: `comment.body`
70+
- **PR Reviews**: `review.body`
71+
- **Other events**: Empty string
72+
73+
**Note**: Using this feature results in the addition of ".github/actions/compute-text/action.yml" file to the repository when the workflow is compiled.
74+
75+
## Related Documentation
76+
77+
- [Frontmatter Options](frontmatter.md) - All configuration options for workflows
78+
- [Workflow Structure](workflow-structure.md) - Directory layout and organization
79+
- [Commands](commands.md) - CLI commands for workflow management

0 commit comments

Comments
 (0)