Skip to content

Commit 1364f1d

Browse files
pelikhanpelikhan
authored
Merge branch 'main' into agent-engine-output-branch
2 parents 84bed29 + 1615f3e commit 1364f1d

19 files changed

Lines changed: 1161 additions & 814 deletions

‎CONTRIBUTING.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Contributing to GitHub Agentic Workflows
2+
3+
Thank you for your interest in contributing to GitHub Agentic Workflows! We welcome contributions from the community and are excited to work with you.
4+
5+
## 🚀 Quick Start for Contributors
6+
7+
1. **Fork and clone the repository**
8+
```bash
9+
git clone https://github.com/your-username/gh-aw.git
10+
cd gh-aw
11+
```
12+
13+
2. **Set up the development environment**
14+
```bash
15+
# Install dependencies
16+
make deps-dev
17+
18+
# Build the project
19+
make build
20+
21+
# Run tests to ensure everything works
22+
make test
23+
```
24+
25+
3. **Make your changes and test them**
26+
```bash
27+
# Format your code
28+
make fmt
29+
30+
# Run linter
31+
make lint
32+
33+
# Run tests
34+
make test
35+
36+
# Compile workflows to ensure compatibility
37+
make recompile
38+
```
39+
40+
4. **Submit your contribution**
41+
- Create a new branch for your feature or fix
42+
- Make your changes
43+
- Run `make agent-finish` to ensure all checks pass
44+
- Submit a pull request
45+
46+
## 🛠️ Development Setup
47+
48+
For detailed development setup instructions, see the [Development Guide](DEVGUIDE.md).
49+
50+
### Prerequisites
51+
- Go 1.24.5 or later
52+
- GitHub CLI (`gh`) installed and authenticated
53+
- Git
54+
55+
### Build Commands
56+
- `make deps` - Install basic dependencies
57+
- `make deps-dev` - Install development dependencies (including linter)
58+
- `make build` - Build the binary
59+
- `make test` - Run tests
60+
- `make lint` - Run linter
61+
- `make fmt` - Format code
62+
- `make agent-finish` - Run complete validation (build, test, recompile, format, lint)
63+
64+
## 📝 How to Contribute
65+
66+
### Reporting Issues
67+
- Use the GitHub issue tracker to report bugs
68+
- Include detailed steps to reproduce the issue
69+
- Include version information (`./gh-aw version`)
70+
71+
### Suggesting Features
72+
- Open an issue describing your feature request
73+
- Explain the use case and how it would benefit users
74+
- Include examples if applicable
75+
76+
### Contributing Code
77+
78+
#### Code Style
79+
- Follow Go best practices and idioms
80+
- Use `make fmt` to format your code
81+
- Ensure `make lint` passes without errors
82+
- Write tests for new functionality
83+
84+
#### Console Output
85+
When adding CLI output, always use the styled console functions from `pkg/console`:
86+
87+
```go
88+
import "github.com/githubnext/gh-aw/pkg/console"
89+
90+
// Use styled messages instead of plain fmt.Printf
91+
fmt.Println(console.FormatSuccessMessage("Operation completed"))
92+
fmt.Println(console.FormatInfoMessage("Processing workflow..."))
93+
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))
94+
```
95+
96+
#### File Organization
97+
- Prefer creating new files grouped by functionality over adding to existing files
98+
- Place new CLI commands in `pkg/cli/`
99+
- Place workflow processing logic in `pkg/workflow/`
100+
- Add tests alongside your code (e.g., `feature.go` and `feature_test.go`)
101+
102+
### Documentation
103+
- Update documentation for any new features
104+
- Add examples where helpful
105+
- Ensure documentation is clear and concise
106+
107+
### Testing
108+
- Write unit tests for new functionality
109+
- Ensure all tests pass (`make test`)
110+
- Test manually with real workflows when possible
111+
112+
## 🔄 Pull Request Process
113+
114+
1. **Before submitting:**
115+
- Run `make agent-finish` to ensure all checks pass
116+
- Test your changes manually
117+
- Update documentation if needed
118+
119+
2. **Pull request requirements:**
120+
- Clear description of what the PR does
121+
- Reference any related issues
122+
- Include tests for new functionality
123+
- Ensure CI passes
124+
125+
3. **Review process:**
126+
- Maintainers will review your PR
127+
- Address any feedback
128+
- Once approved, your PR will be merged
129+
130+
## 🏗️ Project Structure
131+
132+
```
133+
/
134+
├── cmd/gh-aw/ # Main CLI application
135+
├── pkg/ # Core Go packages
136+
│ ├── cli/ # CLI command implementations
137+
│ ├── console/ # Console formatting utilities
138+
│ ├── parser/ # Markdown frontmatter parsing
139+
│ └── workflow/ # Workflow compilation and processing
140+
├── docs/ # Documentation
141+
├── .github/workflows/ # Sample workflows and CI
142+
└── Makefile # Build automation
143+
```
144+
145+
## 🤝 Community
146+
147+
- Join the `#continuous-ai` channel in the [GitHub Next Discord](https://gh.io/next-discord)
148+
- Participate in discussions on GitHub issues
149+
- Help other contributors and users
150+
151+
## 📜 Code of Conduct
152+
153+
This project follows the GitHub Community Guidelines. Please be respectful and inclusive in all interactions.
154+
155+
## ❓ Getting Help
156+
157+
- Check the [Documentation](docs/index.md)
158+
- Read the [Development Guide](DEVGUIDE.md)
159+
- Ask questions in GitHub issues or Discord
160+
- Look at existing code and tests for examples
161+
162+
Thank you for contributing to GitHub Agentic Workflows! 🎉

‎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: 14 additions & 175 deletions
Original file line numberDiff line numberDiff line change
@@ -3,194 +3,33 @@
33
Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/).
44

55
> [!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.
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
8-
## ⚡ Quick Start (30 seconds)
8+
## 🚀 Quick Start
99

10-
Install the extension:
10+
Ready to get your first agentic workflow running? Follow our step-by-step [Quick Start Guide](docs/quick-start.md) to install the extension, add a sample workflow, and see it in action.
1111

12-
```bash
13-
gh extension install githubnext/gh-aw
14-
```
12+
## 📖 Overview
1513

16-
Now, add a weekly research report to your repo (this adds [this sample](https://github.com/githubnext/agentics/blob/main/workflows/weekly-research.md)):
14+
Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See [Concepts](docs/concepts.md).
1715

18-
```bash
19-
gh aw add weekly-research -r githubnext/agentics --pr
20-
```
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`:
16+
## 📖 Documentation
2217

23-
```
24-
.github/
25-
└── workflows/
26-
├── weekly-research.md # Agentic Workflow
27-
└── weekly-research.lock.yml # Compiled GitHub Actions Workflow
28-
```
18+
For complete documentation, examples, and guides, see the [Documentation](docs/index.md).
2919

30-
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:
20+
## 🤝 Contributing
3121

32-
```bash
33-
# For Claude engine (default)
34-
gh secret set ANTHROPIC_API_KEY -a actions --body <your-anthropic-api-key>
22+
We welcome contributions to GitHub Agentic Workflows! Here's how you can help:
3523

36-
# For Codex engine (experimental, requires "--engine codex")
37-
gh secret set OPENAI_API_KEY -a actions --body <your-openai-api-key>
38-
```
24+
- **🐛 Report bugs and request features** by filing issues in this repository
25+
- **📖 Improve documentation** by contributing to our docs
26+
- **🔧 Contribute code** by following our [Development Guide](DEVGUIDE.md)
27+
- **💡 Share ideas** in the `#continuous-ai` channel in the [GitHub Next Discord](https://gh.io/next-discord)
3928

40-
Once you've reviewed and merged the PR you're all set! Each week, the workflow will run automatically and create a research report issue in your repository. If you're in a hurry and would like to run the workflow immediately, you can do so using:
41-
42-
```bash
43-
gh aw run weekly-research
44-
```
45-
46-
You can explore other samples at [githubnext/agentics](https://github.com/githubnext/agentics). You can also copy those samples and write your own workflows. Any repository that has a "workflows" directory can be used as a source of workflows.
47-
48-
## 📝 Agentic Workflow Example
49-
50-
Here's what a simple agentic workflow looks like. This example automatically triages new issues:
51-
52-
```markdown
53-
---
54-
on:
55-
issues:
56-
types: [opened]
57-
58-
permissions:
59-
contents: read # Minimal permissions for main job
60-
61-
tools:
62-
github:
63-
allowed: [add_issue_comment]
64-
65-
output:
66-
issue:
67-
title-prefix: "[triage] "
68-
labels: [automation, triage]
69-
70-
timeout_minutes: 5
71-
---
72-
73-
# Issue Triage
74-
75-
Analyze issue #${{ github.event.issue.number }} and help with triage:
76-
77-
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
80-
81-
Keep responses concise and helpful.
82-
```
83-
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-
90-
## 📂 Available Demonstrator Workflows from "[The Agentics](https://github.com/githubnext/agentics?tab=readme-ov-file#-the-agentics)"
91-
92-
### Research & Planning Workflows
93-
- [📚 Weekly Research](https://github.com/githubnext/agentics?tab=readme-ov-file#-weekly-research) - Collect research updates and industry trends
94-
- [👥 Daily Team Status](https://github.com/githubnext/agentics?tab=readme-ov-file#-daily-team-status) - Assess repository activity and create status reports
95-
- [📋 Daily Plan](https://github.com/githubnext/agentics?tab=readme-ov-file#-daily-plan) - Update planning issues for team coordination
96-
- [🏷️ Issue Triage](https://github.com/githubnext/agentics?tab=readme-ov-file#️-issue-triage) - Triage issues and pull requests
97-
98-
### Coding & Development Workflows
99-
- [📦 Daily Dependency Updater](https://github.com/githubnext/agentics?tab=readme-ov-file#-daily-dependency-updater) - Update dependencies and create pull requests
100-
- [📖 Regular Documentation Update](https://github.com/githubnext/agentics?tab=readme-ov-file#-regular-documentation-update) - Update documentation automatically
101-
- [🔍 Daily QA](https://github.com/githubnext/agentics?tab=readme-ov-file#-daily-qa) - Perform quality assurance tasks
102-
- [🔍 Daily Accessibility Review](https://github.com/githubnext/agentics?tab=readme-ov-file#-daily-accessibility-review) - Review application accessibility
103-
104-
105-
## 📖 Deep Dive
106-
107-
### What's this extension for?
108-
109-
The extension is to support [Continuous AI](https://githubnext.com/projects/continuous-ai) workflows. Continuous AI is a label we've identified for all uses of automated AI to support software collaboration on any platform.
110-
111-
We've chosen the term "Continuous AI” to align with the established concept of Continuous Integration/Continuous Deployment (CI/CD). Just as CI/CD transformed software development by automating integration and deployment, Continuous AI covers the ways in which AI can be used to automate and enhance collaboration workflows.
112-
113-
“Continuous AI” is not a term GitHub owns, nor a technology GitHub builds: it's a term we use to focus our minds, and which we're introducing to the industry. This means Continuous AI is an open-ended set of activities, workloads, examples, recipes, technologies and capabilities; a category, rather than any single tool.
114-
115-
Some examples of Continuous AI are:
116-
117-
* **Continuous Documentation**: Continually populate and update documentation, offering suggestions for improvements.
118-
119-
* **Continuous Code Improvement**: Incrementally improve code comments, tests and other aspects of code e.g. ensuring code comments are up-to-date and relevant.
120-
121-
* **Continuous Triage**: Label, summarize, and respond to issues using natural language.
122-
123-
* **Continuous Summarization**: Provide up-to-date summarization of content and recent events in the software projects.
124-
125-
* **Continuous Fault Analysis**: Watch for failed CI runs and offer explanations of them with contextual insights.
126-
127-
* **Continuous Quality**: Using LLMs to automatically analyze code quality, suggest improvements, and ensure adherence to coding standards.
128-
129-
* **Continuous Team Motivation**: Turn PRs and other team activity into poetry, zines, podcasts; provide nudges, or celebrate team achievements.
130-
131-
* **Continuous Accessibility**: Automatically check and improve the accessibility of code and documentation.
132-
133-
* **Continuous Research**: Automatically research and summarize relevant topics, technologies, and trends to keep the team informed.
134-
135-
So far you've just explored the **Continuous Research** example, but you can write your own workflows to explore all the others! Further samples are available at [githubnext/agentics](https://github.com/githubnext/agentics).
136-
137-
### What are lock files?
138-
139-
Adding an agentic workflow adds two main files, for example:
140-
141-
- `.github/workflows/weekly-research.md`
142-
- `.github/workflows/weekly-research.lock.yml`
143-
144-
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.
145-
146-
### Updating after workflow edits
147-
148-
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:
149-
150-
```bash
151-
gh aw compile
152-
```
153-
154-
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.
155-
156-
### Configuring the agentic processor
157-
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)
178-
179-
## Security of Agentic Workflows
180-
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.
182-
183-
> [!CAUTION]
184-
> GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use.
29+
For development setup and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
18530

18631
## 💬 Share Feedback
18732

18833
We welcome your feedback on GitHub Agentic Workflows! Please file bugs and feature requests as issues in this repository,
18934
and share your thoughts in the `#continuous-ai` channel in the [GitHub Next Discord](https://gh.io/next-discord).
19035

191-
## 🔗 Related Projects
192-
193-
- [Continuous AI](https://githubnext.com/projects/continuous-ai/)
194-
- [GitHub Actions](https://github.com/features/actions)
195-
- [GitHub CLI](https://cli.github.com/)
196-
- [Model Context Protocol](https://modelcontextprotocol.io/)

‎cmd/gh-aw/main.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -353,7 +353,7 @@ func init() {
353353
rootCmd.AddCommand(enableCmd)
354354
rootCmd.AddCommand(disableCmd)
355355
rootCmd.AddCommand(cli.NewLogsCommand())
356-
rootCmd.AddCommand(cli.NewInspectCommand())
356+
rootCmd.AddCommand(cli.NewMCPInspectCommand())
357357
rootCmd.AddCommand(versionCmd)
358358
}
359359

0 commit comments

Comments
 (0)