diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 9e2ca755422..ab4284aa97f 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -152,9 +152,90 @@ imports: The compiler validates `required` fields, `choice` options, array element types, and object `properties`. Unknown keys are compile-time errors. -## Path Formats +## Path Resolution -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}}`. Paths are resolved relative to the importing file; nested and circular imports are supported. +Import paths are resolved using one of three modes depending on their format. + +### Relative paths (default) + +Paths that do not start with `.github/`, `/`, or an `owner/repo/` prefix are resolved relative to the importing workflow's directory. When compiling with the default `--dir` value, that directory is `.github/workflows/`. + +```aw wrap +--- +on: issues +engine: copilot +imports: + - shared/common-tools.md # → .github/workflows/shared/common-tools.md + - ../agents/helper.md # → .github/agents/helper.md (.. goes up from .github/workflows/) +--- +``` + +> [!NOTE] +> This is the existing, backward-compatible behaviour. Workflows that already use relative paths continue to work without any changes. + +### Repo-root-relative paths + +Paths starting with `.github/` or `/` are resolved from the repository root. Absolute paths (`/`) must point inside `.github/` or `.agents/`; any other prefix is rejected at compile time for security. + +```aw wrap +--- +on: pull_request +engine: copilot +imports: + - .github/agents/code-reviewer.md # resolved from repo root + - .github/workflows/shared/app.md # resolved from repo root +--- +``` + +This form is required when workflows in different directories need to import the same shared file using a stable path, and is the supported way to import files from the `.github/agents/` directory. + +### Cross-repo imports + +Paths matching the `owner/repo/path@ref` format are fetched from GitHub at compile time and cached locally. The `@ref` suffix pins the import to a tag, branch, or commit SHA. + +```aw wrap +--- +on: issues +engine: copilot +imports: + - acme-org/shared-workflows/shared/reporting.md@v2.1.0 # pinned to a tag + - acme-org/shared-workflows/shared/tools.md@main # track a branch + - acme-org/shared-workflows/shared/helpers.md@abc1234 # locked to a SHA +--- +``` + +Remote imports are cached in `.github/aw/imports/` by commit SHA, enabling offline compilation. See [Remote Repository Imports](#remote-repository-imports) for details. + +### Worked example — all three forms + +```aw wrap +--- +on: issues +engine: copilot +imports: + # 1. Relative path – resolved relative to .github/workflows/ + - shared/mcp/tavily.md + # 2. Repo-root-relative – resolved from the repository root + - .github/agents/my-expert-agent.md + # 3. Cross-repo – fetched from GitHub at compile time + - acme-org/shared-workflows/shared/reporting.md@v1.0.0 +--- + +# My Workflow + +Use the imported tools, agent, and reporting configuration. +``` + +### Section references and optional imports + +Append `#SectionName` to any path to import a single section from a markdown file: + +``` +imports: + - shared/tools.md#WebSearch +``` + +Use the `{{#import? ...}}` syntax to mark an import as optional, which skips missing files silently instead of failing compilation. ## Remote Repository Imports diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json index 66026536a35..0085ab1f71a 100644 --- a/pkg/parser/schemas/main_workflow_schema.json +++ b/pkg/parser/schemas/main_workflow_schema.json @@ -66,16 +66,16 @@ ] }, "imports": { - "description": "Workflow specifications to import. Supports array form (list of paths) or object form with 'aw' (agentic workflow paths) and 'apm-packages' (APM packages) subfields.", + "description": "Workflow specifications to import. Supports array form (list of paths) or object form with 'aw' (agentic workflow paths) and 'apm-packages' (APM packages) subfields. Path resolution: (1) relative paths (e.g., 'shared/file.md') are resolved relative to the workflow's directory; (2) paths starting with '.github/' or '/' are resolved from the repository root (repo-root-relative); (3) paths matching 'owner/repo/path@ref' are fetched from GitHub at compile time (cross-repo).", "oneOf": [ { "type": "array", - "description": "Array of workflow specifications to import (similar to @include directives but defined in frontmatter). Format: owner/repo/path@ref (e.g., githubnext/agentics/workflows/shared/common.md@v1.0.0). Can be strings or objects with path and inputs. Any markdown files under .github/agents directory are treated as custom agent files and only one agent file is allowed per workflow.", + "description": "Array of workflow specifications to import. Three path formats are supported: relative paths ('shared/file.md'), repo-root-relative paths ('.github/agents/my-agent.md'), and cross-repo paths ('owner/repo/path@ref'). Any markdown files under .github/agents directory are treated as custom agent files and only one agent file is allowed per workflow.", "items": { "oneOf": [ { "type": "string", - "description": "Workflow specification in format owner/repo/path@ref. Markdown files under .github/agents/ are treated as agent configuration files." + "description": "Import path. Use 'shared/file.md' for paths relative to the workflow directory, '.github/agents/my-agent.md' for repo-root-relative paths, or 'owner/repo/path@ref' for cross-repo imports. Markdown files under .github/agents/ are treated as agent configuration files." }, { "type": "object", @@ -85,7 +85,7 @@ "properties": { "path": { "type": "string", - "description": "Workflow specification in format owner/repo/path@ref. Markdown files under .github/agents/ are treated as agent configuration files." + "description": "Import path. Use 'shared/file.md' for paths relative to the workflow directory, '.github/agents/my-agent.md' for repo-root-relative paths, or 'owner/repo/path@ref' for cross-repo imports. Markdown files under .github/agents/ are treated as agent configuration files." }, "inputs": { "type": "object", @@ -131,7 +131,7 @@ "properties": { "uses": { "type": "string", - "description": "Workflow specification in format owner/repo/path@ref. Alias for 'path'." + "description": "Import path (alias for 'path'). Use 'shared/file.md' for paths relative to the workflow directory, '.github/agents/my-agent.md' for repo-root-relative paths, or 'owner/repo/path@ref' for cross-repo imports." }, "with": { "type": "object",