From 177e4ae41fae8455bdad1d295257ddad44ddde2f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 1 Dec 2025 06:09:32 +0000
Subject: [PATCH] docs: Add documentation for shared gh.md workflow

- Document the reusable shared/gh.md workflow in safe-inputs reference
- Add 'Shared gh CLI Tool' subsection with usage examples
- Show how to import and use the gh tool with various commands

Related to #5157
---
 .../src/content/docs/reference/safe-inputs.md | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/src/content/docs/reference/safe-inputs.md b/docs/src/content/docs/reference/safe-inputs.md
index 72b83f7e8..69ab58351 100644
--- a/docs/src/content/docs/reference/safe-inputs.md
+++ b/docs/src/content/docs/reference/safe-inputs.md
@@ -174,6 +174,26 @@ safe-inputs:
       GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 ```
 
+### Shared gh CLI Tool
+
+The repository includes a reusable shared workflow (`shared/gh.md`) that provides a general-purpose gh CLI tool:
+
+```yaml wrap
+imports:
+  - shared/gh.md
+```
+
+This imports a `gh` tool that accepts any gh CLI command as arguments:
+
+```yaml
+# The agent can use:
+gh with args: "pr list --limit 5"
+gh with args: "issue view 123"
+gh with args: "api repos/{owner}/{repo}"
+```
+
+The shared workflow uses `${{ github.token }}` for authentication, providing access based on the workflow's `permissions` configuration.
+
 ## Input Parameters
 
 Define typed parameters with validation: