From 31d9f70b25194d359b5e5d34e1aa92de18bc28c5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 4 Apr 2026 14:50:37 +0000 Subject: [PATCH 1/2] Initial plan From 1fb27608f475c796d3a6bbd5bab4fec6336ee6a4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 4 Apr 2026 14:57:54 +0000 Subject: [PATCH 2/2] docs: document import path resolution modes (relative, repo-root-relative, cross-repo) Agent-Logs-Url: https://github.com/github/gh-aw/sessions/289105c7-d9c0-4813-9f2c-bdc636fce152 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/imports.md | 97 +++++++++++++++++++- pkg/parser/schemas/main_workflow_schema.json | 10 +- 2 files changed, 101 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 9e2ca755422..090af4406e1 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -154,7 +154,102 @@ The compiler validates `required` fields, `choice` options, array element types, ## 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}}`. Paths are resolved relative to the importing file; nested and circular imports are supported. +Import paths support three resolution modes: + +| Mode | Syntax | Resolved against | +|------|--------|-----------------| +| Relative (default) | `shared/file.md`, `../file.md` | Workflow directory (default `.github/workflows/`) | +| Repo-root-relative | `.github/path/file.md` or `/path/file.md` | Repository root | +| Cross-repo | `owner/repo/path@ref` | Remote GitHub repository | + +Section references (`file.md#SectionName`) and optional imports (`{{#import? file.md}}`) work with all three modes. + +### Relative paths (default) + +Paths that do not start with `.github/`, `/`, or an `owner/repo/` prefix are resolved relative to the workflow's directory (default `.github/workflows/`). This is the backward-compatible, existing behaviour. + +```aw wrap +--- +on: issues +engine: copilot +imports: + - shared/common-tools.md # → .github/workflows/shared/common-tools.md + - ../agents/code-reviewer.md # → .github/agents/code-reviewer.md +--- +``` + +### Repo-root-relative paths + +Paths starting with `.github/` or `/` are resolved from the repository root. Use this form to reference files outside the default workflows directory, such as custom agents in `.github/agents/`. + +```aw wrap +--- +on: pull_request +engine: copilot +imports: + - .github/agents/code-reviewer.md # → {repo-root}/.github/agents/code-reviewer.md +--- +``` + +> [!NOTE] +> For security, all locally-resolved paths must remain within the `.github/` folder. Paths that resolve outside this boundary are rejected at compile time. + +### Cross-repo imports + +Reference shared components from other GitHub repositories using the `owner/repo/path@ref` syntax. The compiler fetches the file from GitHub at compile time and inlines it into the lock file. + +```aw wrap +--- +on: issues +engine: copilot +imports: + - acme-org/shared-workflows/mcp/tavily.md@v1.0.0 # tagged release + - acme-org/shared-workflows/tools/github-setup.md@main # branch + - acme-org/shared-workflows/tools/github-setup.md@abc123 # commit SHA +--- + +# Issue Triage Workflow + +Analyze incoming issues using imported tools and configurations. +``` + +Supported refs: semantic tags (`@v1.0.0`), branches (`@main`), or commit SHAs. Omitting `@ref` defaults to `@main`. See [Reusing Workflows](/gh-aw/guides/packaging-imports/) for installation and update workflows. + +### Worked example + +All three forms can appear in a single frontmatter block: + +```aw wrap +--- +on: pull_request +engine: copilot +imports: + # 1. Relative path — resolved from .github/workflows/ + - shared/common-tools.md + # 2. Repo-root-relative path — resolved from the repository root + - .github/agents/code-reviewer.md + # 3. Cross-repo import — pinned to a release tag + - acme-org/shared-workflows/mcp/tavily.md@v1.0.0 +--- + +# Pull Request Review + +Review the pull request for quality and security issues. +``` + +### Backward compatibility + +The relative-path form has been supported since the beginning. Repo-root-relative paths (`.github/`-prefix and `/`-prefix) and cross-repo imports (`owner/repo/path@ref`) are additive. Existing workflows using relative paths continue to work unchanged. + +### Security constraints + +All locally-resolved paths (relative and repo-root-relative) must remain within the repository's `.github/` folder. Paths that would resolve outside this boundary are rejected at compile time with an error such as: + +``` +security: path ../../../etc/passwd must be within .github folder +``` + +Remote cross-repo imports are fetched from GitHub at compile time and cached by commit SHA in `.github/aw/imports/`. They are not subject to the `.github/` constraint but are subject to standard GitHub repository access controls. ## Remote Repository Imports diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json index 66026536a35..b4441eecdb7 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 modes: (1) relative path (e.g. 'shared/file.md') — resolved relative to the workflow directory (default .github/workflows/); (2) repo-root-relative path starting with '.github/' or '/' (e.g. '.github/agents/my-agent.md') — resolved from the repository root; (3) cross-repo reference 'owner/repo/path@ref' (e.g. 'acme-org/shared/mcp/tavily.md@v1.0.0') — fetched from GitHub at compile time.", "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. Each entry can be: a relative path resolved from .github/workflows/ (e.g. 'shared/file.md'), a repo-root-relative path starting with '.github/' or '/' (e.g. '.github/agents/my-agent.md'), or a cross-repo reference 'owner/repo/path@ref'. Entries can be strings or objects with 'path'/'uses' and 'inputs'/'with' fields. Markdown files under .github/agents/ are treated as custom agent files; 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. Supported forms: relative path ('shared/file.md', resolved from .github/workflows/), repo-root-relative path ('.github/agents/my-agent.md' or '/path/file.md', resolved from the repository root), or cross-repo reference ('owner/repo/path@ref'). 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. Supported forms: relative path ('shared/file.md', resolved from .github/workflows/), repo-root-relative path ('.github/agents/my-agent.md' or '/path/file.md', resolved from the repository root), or cross-repo reference ('owner/repo/path@ref'). 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. Supported forms: relative path ('shared/file.md', resolved from .github/workflows/), repo-root-relative path ('.github/agents/my-agent.md' or '/path/file.md', resolved from the repository root), or cross-repo reference ('owner/repo/path@ref'). Alias for 'path'." }, "with": { "type": "object",