From e9c8bfc1532f630ef06b0acd3a0892bf98476718 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 13 Aug 2025 19:09:43 +0100 Subject: [PATCH 1/2] update docs --- README.md | 14 ++++++-- docs/commands.md | 37 ++++++++++++++++++++- docs/frontmatter.md | 22 +++++++++--- docs/mcps.md | 8 ++--- docs/secrets.md | 81 ++++++++++++++++++++++++++++++++++++++++++--- docs/tools.md | 12 ------- pkg/cli/commands.go | 2 +- 7 files changed, 145 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 4156a9a8e8..7dccafb328 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,14 @@ gh aw add weekly-research -r githubnext/agentics --pr 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`. -Your repository will also need a ANTHROPIC_API_KEY or OPENAI_API_KEY Actions secret set up to run workflows that use AI models. You can add this using one of the following commands: +Your repository will also need an ANTHROPIC_API_KEY (for Claude) or OPENAI_API_KEY (for Codex) Actions secret set up to run workflows that use AI models. You can add this using one of the following commands: ```bash +# For Claude engine (default) gh secret set ANTHROPIC_API_KEY -a actions --body -#gh secret set OPENAI_API_KEY -a actions --body + +# For Codex engine (experimental) +gh secret set OPENAI_API_KEY -a actions --body ``` 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: @@ -126,12 +129,17 @@ You will see the changes reflected in the `.lock.yml` file, which is the actual 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. ```markdown -engine: codex # Optional: specify AI engine (claude, codex) +engine: claude # Default: Claude Code +engine: codex # Experimental: OpenAI Codex CLI with MCP support ``` You can also specify this on the command line when adding or running workflows: ```bash +# Use Claude (default) +gh aw add weekly-research --engine claude + +# Use Codex (experimental) gh aw add weekly-research --engine codex ``` diff --git a/docs/commands.md b/docs/commands.md index 245921573a..3c26a39dc8 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -26,6 +26,15 @@ gh aw compile # Compile workflows with verbose output gh aw compile --verbose +# Compile workflows with schema validation +gh aw compile --validate + +# Compile workflows with engine override +gh aw compile --engine codex + +# Generate GitHub Copilot instructions file +gh aw compile --instructions + # Compile workflows and generate auto-compile workflow for automatic compilation gh aw compile --auto-compile @@ -194,6 +203,15 @@ gh aw list --packages # List only local packages gh aw list --packages --local + +# Uninstall a workflow package globally +gh aw uninstall org/repo + +# Uninstall a workflow package locally +gh aw uninstall org/repo --local + +# Show version information +gh aw version ``` **Package Management Features:** @@ -210,7 +228,24 @@ gh aw list --packages --local - Network access to download from GitHub repositories - Target repository must have a `workflows/` directory containing `.md` files -## 📝 Creating New Workflows +## �️ Package Removal + +```bash +# Uninstall workflow packages globally (default) +gh aw uninstall org/repo + +# Uninstall packages locally from current project +gh aw uninstall org/repo --local +``` + +**Package Removal Features:** + +- **Clean Uninstall**: Removes all downloaded workflow files and metadata +- **Global vs Local**: Supports both global (`~/.aw/packages/`) and local (`.aw/packages/`) removal +- **Safe Operation**: Only removes the specified package without affecting others +- **Validation**: Confirms package exists before attempting removal + +## �📝 Creating New Workflows The `gh aw new` command creates a new workflow markdown file with comprehensive template content and examples. diff --git a/docs/frontmatter.md b/docs/frontmatter.md index 381ccd9eab..c0aac27643 100644 --- a/docs/frontmatter.md +++ b/docs/frontmatter.md @@ -148,16 +148,24 @@ If you specify any permission, unspecified ones are set to `none`. Specifies which AI engine to use. Defaults to `claude`. +```yaml +engine: claude # Default: Claude Code +engine: codex # Experimental: OpenAI Codex CLI with MCP support +``` + +**Engine Override**: +You can override the engine specified in frontmatter using CLI flags: +```bash +gh aw add weekly-research --engine codex +gh aw compile --engine claude +``` + ### Simple String Format ```yaml engine: claude # or codex ``` -**Available engines:** -- `claude` (default): Claude Code with full MCP tool support and allow-listing (see [MCP Guide](mcps.md)) -- `codex` (**experimental**): Codex with OpenAI endpoints - ### Extended Object Format ```yaml @@ -170,7 +178,11 @@ engine: **Fields:** - **`id`** (required): Engine identifier (`claude`, `codex`) - **`version`** (optional): Action version (`beta`, `stable`) -- **`model`** (optional): Specific LLM model +- **`model`** (optional): Specific LLM model to use + +**Model Defaults:** +- **Claude**: Uses the default model from the claude-code-base-action (typically latest Claude model) +- **Codex**: Defaults to `o4-mini` when no model is specified ## Cost Control Options diff --git a/docs/mcps.md b/docs/mcps.md index 68de3864bf..f447b42621 100644 --- a/docs/mcps.md +++ b/docs/mcps.md @@ -40,10 +40,10 @@ tools: Different AI engines support different MCP features: -- **Claude** (default): ✅ Full MCP support (stdio and HTTP) -- **Codex**: ✅ Limited MCP support (stdio only) -- **AI Inference**: ✅ GitHub MCP support -- **Other engines**: Varies by engine +- **Claude** (default): ✅ Full MCP support (stdio, Docker, HTTP) +- **Codex** (experimental): ✅ Limited MCP support (stdio only, no HTTP) + +**Note**: When using Codex engine, HTTP MCP servers will be ignored and only stdio-based servers will be configured. ## MCP Server Types diff --git a/docs/secrets.md b/docs/secrets.md index 3f76607982..4e6eb524f5 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -18,17 +18,88 @@ permissions: ``` ## User-Defined Secrets -You need to define custom secrets in your repository or organization settings to enable usage of your chosen agentic processor. These secrets will be referenced in generated workflows. -### `ANTHROPIC_API_KEY` +You need to define custom secrets in your repository or organization settings to enable usage of your chosen agentic processor and external services. + +### AI Engine Secrets + +#### `ANTHROPIC_API_KEY` - **Purpose**: Claude engine access -- **Required for**: `engine: claude` workflows +- **Required for**: `engine: claude` workflows (default) - **Setup**: Add to repository or organization secrets +- **Usage**: Automatically used by Claude engine -### `OPENAI_API_KEY` +#### `OPENAI_API_KEY` - **Purpose**: Codex and OpenAI-based engines -- **Required for**: `engine: codex` workflows +- **Required for**: `engine: codex` workflows (experimental) - **Setup**: Add to repository or organization secrets +- **Usage**: Automatically used by Codex engine + +### MCP Server Secrets + +Custom secrets for MCP servers are referenced using `${secrets.SECRET_NAME}` syntax: + +```yaml +tools: + trello: + mcp: + type: stdio + command: "python" + args: ["-m", "trello_mcp"] + env: + TRELLO_TOKEN: "${secrets.TRELLO_TOKEN}" + TRELLO_KEY: "${secrets.TRELLO_KEY}" + allowed: ["list_boards", "create_card"] +``` + +### Custom Environment Variables + +You can define custom environment variables in the workflow frontmatter: + +```yaml +env: + NODE_ENV: "production" + DEBUG: "false" + CUSTOM_CONFIG: "${secrets.MY_CONFIG}" +``` + +## Setting Up Secrets + +### Repository Secrets +```bash +# Set secrets for a specific repository +gh secret set ANTHROPIC_API_KEY -a actions --body +gh secret set TRELLO_TOKEN -a actions --body +``` + +### Organization Secrets +```bash +# Set secrets for all repositories in an organization +gh secret set ANTHROPIC_API_KEY -a actions --org --body +``` + +## Security Best Practices + +### Secret Access +- Secrets are only accessible to workflows with appropriate permissions +- Secrets are automatically masked in workflow logs +- Use minimal scope secrets when possible + +### Secret Naming +- Use UPPER_CASE names for secrets +- Use descriptive names that indicate the service: `TRELLO_TOKEN`, `SLACK_WEBHOOK` +- Avoid exposing secret values in frontmatter or markdown content + +### MCP Server Security +```yaml +# ✅ Good: Secret reference +env: + API_KEY: "${secrets.MY_API_KEY}" + +# ❌ Bad: Hardcoded value +env: + API_KEY: "sk-1234567890abcdef" +``` ## Related Documentation diff --git a/docs/tools.md b/docs/tools.md index 9a424d44cb..641050c855 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -119,18 +119,6 @@ tools: Bash: ["echo", "ls", "git", "npm test"] ``` -## Engine Compatibility - -### Claude Engine -- ✅ GitHub tools -- ✅ Claude-specific tools -- ✅ Custom MCP tools (see [MCP Guide](mcps.md)) - -### Codex Engine -- ✅ GitHub tools -- ❌ Claude-specific tools (ignored) -- ✅ Custom MCP tools (stdio only, see [MCP Guide](mcps.md)) - ## Security Considerations diff --git a/pkg/cli/commands.go b/pkg/cli/commands.go index 2944ae5484..f9a7e569fe 100644 --- a/pkg/cli/commands.go +++ b/pkg/cli/commands.go @@ -3063,7 +3063,7 @@ func RunWorkflowOnGitHub(workflowIdOrName string, verbose bool) error { return nil } -// IsRunnable checks if a workflow can be run locally (has schedule or workflow_dispatch trigger) +// IsRunnable checks if a workflow can be run (has schedule or workflow_dispatch trigger) func IsRunnable(markdownPath string) (bool, error) { // Read the file contentBytes, err := os.ReadFile(markdownPath) From b907df4da1728c2bb1752980359f6fe3e131246d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 13 Aug 2025 20:22:52 +0100 Subject: [PATCH 2/2] tweaks --- DEVGUIDE.md | 4 ++-- README.md | 6 +++--- cmd/gh-aw/main.go | 12 ++++++++++++ docs/frontmatter.md | 4 ++-- docs/index.md | 4 ++-- pkg/cli/commands.go | 4 ++-- 6 files changed, 23 insertions(+), 11 deletions(-) diff --git a/DEVGUIDE.md b/DEVGUIDE.md index 03c4ef82ab..015e28e2ac 100644 --- a/DEVGUIDE.md +++ b/DEVGUIDE.md @@ -1,7 +1,7 @@ # Developer Guide -> [!CAUTION] -> This extension is a research project from GitHub Next. 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. +> [!WARNING] +> 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. This guide provides comprehensive information for developers working on gh-aw, including setup, development workflow, testing, and contribution guidelines. diff --git a/README.md b/README.md index 7dccafb328..f4a7e37d0b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # 🤖 GitHub Agentic Workflows -Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/) +Write agentic workflows in natural language markdown, and run them in GitHub Actions. From [GitHub Next](https://githubnext.com/). -> [!CAUTION] -> This extension is a research project from GitHub Next. 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. +> [!WARNING] +> 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. ## ⚡ Quick Start (30 seconds) diff --git a/cmd/gh-aw/main.go b/cmd/gh-aw/main.go index 3234cdb3a4..3324ef31b0 100644 --- a/cmd/gh-aw/main.go +++ b/cmd/gh-aw/main.go @@ -287,6 +287,18 @@ func init() { // Add global verbose flag to root command rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output showing detailed information") + // Override the help function to hide completion command + originalHelpFunc := rootCmd.HelpFunc() + rootCmd.SetHelpFunc(func(cmd *cobra.Command, args []string) { + // Hide completion command before displaying help + for _, subCmd := range cmd.Commands() { + if subCmd.Name() == "completion" { + subCmd.Hidden = true + } + } + originalHelpFunc(cmd, args) + }) + // Add number flag to add command addCmd.Flags().IntP("number", "c", 1, "Create multiple numbered copies") diff --git a/docs/frontmatter.md b/docs/frontmatter.md index c0aac27643..d2abfe45eb 100644 --- a/docs/frontmatter.md +++ b/docs/frontmatter.md @@ -105,9 +105,9 @@ analyze and provide a helpful summary. The current context text is: "${{ needs.task.outputs.text }}" ``` -## Context Text Variable (`text`) +## Context Text (`needs.task.outputs.text`) -All workflows have access to a computed `text` output variable that provides context based on the triggering event: +All workflows have access to a special computed `needs.task.outputs.text` value that provides context based on the triggering event: ```markdown # Analyze this content: "${{ needs.task.outputs.text }}" diff --git a/docs/index.md b/docs/index.md index 09994bfdc8..ba45de5eac 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # 📖 GitHub Agentic Workflows Documentation -> [!CAUTION] -> This extension is a research project from GitHub Next. 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. +> [!WARNING] +> 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. Complete documentation for creating and managing agentic workflows with GitHub Actions. diff --git a/pkg/cli/commands.go b/pkg/cli/commands.go index f9a7e569fe..cb7337f63b 100644 --- a/pkg/cli/commands.go +++ b/pkg/cli/commands.go @@ -2824,9 +2824,9 @@ func listPackageWorkflows(verbose bool) error { // Mark packages with their location for i := range packages { if local { - packages[i].Name = packages[i].Name + " (local)" + packages[i].Name = packages[i].Name + ", local" } else { - packages[i].Name = packages[i].Name + " (global)" + packages[i].Name = packages[i].Name + ", global" } }