From 1d163431b1eba7219df6337073d0162b5bbe9e06 Mon Sep 17 00:00:00 2001
From: GitHub Actions <noreply@github.com>
Date: Sun, 25 Jan 2026 17:59:23 +0000
Subject: [PATCH] docs: update documentation for setup-cli action and MCP mode
 deprecation

- Add setup-cli GitHub Action documentation to CLI guide
- Document MCP mode field removal and migration path
- Add troubleshooting section for deprecated mode field

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/src/content/docs/setup/cli.md            | 37 +++++++++++++++++
 .../docs/troubleshooting/common-issues.md     | 41 +++++++++++++++++++
 2 files changed, 78 insertions(+)

diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index e03125ee59b..088c43b83e7 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -89,6 +89,43 @@ curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.s
 
 Installs to `~/.local/share/gh/extensions/gh-aw/gh-aw` and works with all `gh aw` commands. Supports Linux, macOS, FreeBSD, and Windows.
 
+### GitHub Actions Setup Action
+
+Install the CLI in GitHub Actions workflows using the `setup-cli` action:
+
+``````yaml wrap
+- name: Install gh-aw CLI
+  uses: githubnext/gh-aw/actions/setup-cli@main
+  with:
+    version: v0.37.18
+``````
+
+The action automatically installs the specified version with checksum verification and platform detection. Useful for CI/CD pipelines, workflow testing, and automation scripts.
+
+**Features:**
+- Version validation against GitHub releases
+- SHA256 checksum verification for security
+- Automatic platform and architecture detection
+- Fallback installation methods for reliability
+- Works on Linux, macOS, Windows, and FreeBSD
+
+**Example with verification:**
+
+``````yaml wrap
+- name: Install gh-aw CLI
+  id: install
+  uses: githubnext/gh-aw/actions/setup-cli@main
+  with:
+    version: v0.37.18
+
+- name: Verify installation
+  run: |
+    gh aw version
+    echo "Installed: ${{ steps.install.outputs.installed-version }}"
+``````
+
+See the [setup-cli action README](https://github.com/githubnext/gh-aw/blob/main/actions/setup-cli/README.md) for complete documentation and examples.
+
 ### GitHub Enterprise Server Support
 
 Configure for GitHub Enterprise Server deployments:
diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
index 3b94f45b08a..c3cb3b532d3 100644
--- a/docs/src/content/docs/troubleshooting/common-issues.md
+++ b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -152,6 +152,47 @@ mcp-servers:
       API_KEY: "${{ secrets.MCP_API_KEY }}"
 ```
 
+### Deprecated `mode` Field in Custom MCP Servers
+
+**Error Message:**
+
+```text
+Additional property mode is not allowed
+```
+
+**Cause:** The `mode` field was removed from custom MCP server configurations. This field was previously used to specify the MCP server transport type but has been deprecated.
+
+**Solution:** Remove the `mode` field from your custom MCP server configurations. The transport type is now automatically detected based on the configuration:
+
+```yaml wrap
+# Before (deprecated)
+mcp-servers:
+  my-server:
+    command: "npx"
+    args: ["@myorg/mcp-server"]
+    mode: "stdio"  # Remove this line
+    allowed: ["*"]
+
+# After (correct)
+mcp-servers:
+  my-server:
+    command: "npx"
+    args: ["@myorg/mcp-server"]
+    allowed: ["*"]
+```
+
+**Automatic Migration:** Run `gh aw fix --write` to automatically remove deprecated `mode` fields from all workflow files:
+
+```bash wrap
+gh aw fix --write
+```
+
+The `fix` command applies the `mcp-mode-to-type` codemod which removes the `mode` field while preserving all other configuration.
+
+> [!NOTE]
+> GitHub MCP Server Configuration
+> The `mode` field is still valid for the GitHub MCP server (`tools.github.mode`) to choose between `local` (Docker-based) and `remote` (hosted) modes. This deprecation only affects custom MCP servers defined in the `mcp-servers:` section.
+
 ### Playwright Network Access Denied
 
 Add blocked domains to the `allowed_domains` list: