Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 4 additions & 47 deletions docs/src/content/docs/reference/templating.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,17 +98,7 @@ The template system supports only basic conditionals - no nesting, `else` clause

## Runtime Imports

Runtime imports allow you to include content from files and URLs directly within your workflow prompts **at runtime** during GitHub Actions execution. This differs from [frontmatter imports](/gh-aw/reference/imports/) which are processed at compile-time.

**Security Note:** File imports are **restricted to the `.github` folder** in your repository. This ensures workflow configurations cannot access arbitrary files in your codebase.

Runtime imports use the macro syntax: `{{#runtime-import filepath}}`

The macro supports:
- Line range extraction (e.g., `:10-20` for lines 10-20)
- URL fetching with automatic caching
- Content sanitization (front matter removal, macro detection)
- Automatic `.github/` prefix handling
Runtime imports include content from files and URLs in workflow prompts **at runtime** (unlike [compile-time imports](/gh-aw/reference/imports/)). File paths are restricted to the `.github` folder. Use `{{#runtime-import filepath}}` or `{{#runtime-import? filepath}}` for optional imports.
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intro states that runtime-import file paths are restricted to the .github folder, but the runtime implementation also supports importing from the top-level .agents/ directory and (for paths without an explicit prefix) resolves relative to .github/workflows rather than .github/. Consider updating this sentence to reflect the actual resolution rules (e.g., .github/workflows default + explicit .github/... and .agents/... support) so readers don’t form incorrect expectations.

See below for a potential fix:

Runtime imports include content from files and URLs in workflow prompts **at runtime** (unlike [compile-time imports](/gh-aw/reference/imports/)). For security, runtime file paths are resolved within your repository and may only target files under `.github/workflows` (default), explicitly-prefixed `.github/...` paths, or the top-level `.agents/` directory. Use `{{#runtime-import filepath}}` or `{{#runtime-import? filepath}}` for optional imports.

### Macro Syntax

Use `{{#runtime-import filepath}}` to include file content at runtime. Optional imports use `{{#runtime-import? filepath}}` which don't fail if the file is missing.

**Important:** By default, file paths are resolved relative to `.github/workflows`. You can also explicitly target files under `.github/` (using a `.github/...` path) or the top-level `.agents/` directory (using an `.agents/...` path):

Copilot uses AI. Check for mistakes.

### Macro Syntax

Expand Down Expand Up @@ -169,18 +159,11 @@ All runtime imports include automatic security protections.

**Content Sanitization:** YAML front matter and HTML/XML comments are automatically stripped. GitHub Actions expressions (`${{ ... }}`) are **rejected with error** to prevent template injection and unintended variable expansion.

**Path Validation:**

File paths are **restricted to the `.github` folder** to prevent access to arbitrary repository files:
**Path Validation:** File paths are restricted to the `.github` folder to prevent access to arbitrary repository files. Path traversal and absolute paths are rejected:

```aw wrap
# ✅ Valid - Files in .github folder
{{#runtime-import shared-instructions.md}} # Loads .github/shared-instructions.md
{{#runtime-import .github/shared-instructions.md}} # Same - .github/ prefix is trimmed

# ❌ Invalid - Security violations
{{#runtime-import ../src/config.go}} # Error: Relative traversal outside .github
{{#runtime-import /etc/passwd}} # Error: Absolute path not allowed
{{#runtime-import ../src/config.go}} # Error: Relative traversal outside .github
{{#runtime-import /etc/passwd}} # Error: Absolute path not allowed
Comment on lines +165 to +166
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Path Validation example {{#runtime-import ../src/config.go}} may not actually be rejected by the runtime importer: with the current resolution logic, ../src/config.go can normalize to a path that still stays inside .github/ (e.g., resolving from .github/workflows up to .github/src/...). Use an example that reliably escapes .github (such as ../../src/config.go, or .github/../src/config.go) or reword the text to clarify that only paths that resolve outside .github are rejected.

Copilot uses AI. Check for mistakes.
```

### Caching
Expand All @@ -195,32 +178,6 @@ Runtime imports are processed before other substitutions:
2. `${GH_AW_EXPR_*}` variable interpolation
3. `{{#if}}` template conditionals rendered

### Common Use Cases

**Shared instructions from a file:**

```aw wrap
# Code Review Agent

{{#runtime-import workflows/shared/review-standards.md}}
<!-- Loads .github/workflows/shared/review-standards.md -->

Review the pull request changes.
```

**External content from a URL, with line range:**

```aw wrap
# Security Audit

Follow this checklist:

{{#runtime-import https://company.com/security/api-checklist.md}}

Reference implementation (lines 100-150):
{{#runtime-import docs/engine.go:100-150}}
```

### Limitations

- **`.github` folder only:** File paths are restricted to `.github` folder for security
Expand Down
Loading