From 34b24f85dc981c8ba04006f6287ee893eed8df44 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 1 Jan 2026 17:59:13 +0000 Subject: [PATCH] Document shared workflow detection feature MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates documentation to reflect the shared workflow detection feature added in PR #8468. Workflows without an 'on' field are now automatically detected as shared workflow components and skip compilation with an informative message. Changes: - Added shared workflow detection notes to CLI compile command docs - Added new "Shared Workflow Components" section to imports reference - Included example output showing the compiler's informative message 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- docs/src/content/docs/reference/imports.md | 27 ++++++++++++++++++++++ docs/src/content/docs/setup/cli.md | 2 ++ 2 files changed, 29 insertions(+) diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 67e19cca8ce..0782e475388 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -39,6 +39,33 @@ Workflow instructions here... {{#import shared/common-tools.md}} ``` +## Shared Workflow Components + +Workflows without an `on` field are automatically detected as shared workflow components. These files are validated but not compiled into GitHub Actions, as they are meant to be imported by other workflows. When you attempt to compile a shared workflow directly, the compiler displays an informative message and skips compilation: + +```bash wrap +$ gh aw compile shared/mcp/deepwiki.md +ℹī¸ Shared agentic workflow detected: deepwiki.md + +This workflow is missing the 'on' field and will be treated as a shared workflow component. +Shared workflows are reusable components meant to be imported by other workflows. + +To use this shared workflow: + 1. Import it in another workflow's frontmatter: + --- + on: issues + imports: + - shared/mcp/deepwiki.md + --- + + 2. Compile the workflow that imports it + +Skipping compilation. +✓ Compiled 1 workflow(s): 0 error(s), 0 warning(s) +``` + +This allows you to organize reusable components in your repository without generating unnecessary lock files. + ## Path Formats Import paths support local files (`shared/file.md`, `../file.md`), remote repositories (`owner/repo/file.md@v1.0.0`), and section references (`file.md#SectionName`). Optional imports use `{{#import? file.md}}` syntax in markdown. diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index a1fc7e331ef..819d4682547 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -208,6 +208,8 @@ gh aw compile --purge # Remove orphaned .lock.yml files **Strict Mode (`--strict`):** Enforces security best practices: no write permissions (use [safe-outputs](/gh-aw/reference/safe-outputs/)), explicit `network` config, no wildcard domains, pinned Actions, no deprecated fields. See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict). +**Shared Workflows:** Workflows without an `on` field are automatically detected as shared workflow components intended for import by other workflows. These files are validated using a relaxed schema that permits optional markdown content and skip compilation with an informative message. To use a shared workflow, import it in another workflow's frontmatter or with markdown directives. See [Imports reference](/gh-aw/reference/imports/). + ### Testing #### `trial`