Text of github.github.com › gh-aw › reference › imports as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Imports | GitHub Agentic Workflows

Skip to main content Imports Syntax Section titled “Syntax” Use imports: in frontmatter or {{#runtime-import ...}} in markdown to share workflow components across multiple workflows. --- on : issues engine : copilot imports : - shared/common-tools.md - shared/mcp/tavily.md --- # Your Workflow Workflow instructions here... Parameterized imports ( uses / with ) Section titled “Parameterized imports (uses/with)” Shared workflows that declare an import-schema accept runtime parameters.

Use the uses / with form to pass values: --- on : issues engine : copilot imports : - uses : shared/mcp/serena.md with : languages : [ " go " , " typescript " ] --- uses is an alias for path ; with is an alias for inputs . In nested frontmatter imports, relative paths (not starting with .github/ or / ; see Path Resolution ) such as shared/graders/recurrence-determinism.md resolve from the root workflow directory. Bare names ( common.md ) and ./ paths resolve from the importing file.

Lock-file hashes follow the same rules, so changes to nested components invalidate the importing workflow’s lock. Conditional frontmatter imports are not supported. To vary prompt content by experiment, keep imports unconditional and wrap an optional {{#runtime-import? ...}} in an {{#if experiments.<name> ...}} block. The optional form is not promoted to lock-file macros, so it is injected only when the condition is true at runtime.

Single-import constraint Section titled “Single-import constraint” A file can appear at most once in an import graph. Repeated imports with identical with values are silently deduplicated; different with values are a compile-time error: import conflict: 'shared/mcp/serena.md' is imported more than once with different 'with' values. An imported workflow can only be imported once per workflow. Previous 'with': {"languages":["go"]} New 'with': {"languages":["typescript"]} In markdown, {{#runtime-import filepath}} injects another file’s content into the body at that position, for reusable prompt snippets, tone instructions, or reference material.

Runtime-imported markdown shares the main workflow’s compiler-selected non-secret bindings ( env.* , compound expressions, and conditions). gh-aw validates the whole nested local runtime-import tree at compile time. Job-output references must be available before activation, such as ${{ needs.pre_activation.outputs.activated }} . Runtime imports accept only local files under .github or explicit .agents/ paths and never fetch from the network.

For external content, put the URL in the prompt and let the agent retrieve it inside the AWF sandbox under the configured network policy. Frontmatter compile-time imports are unchanged. --- on : schedule engine : copilot --- {{#runtime-import .github/shared/editorial.md}} # Daily Report Generate the daily report. Use {{#runtime-import? filepath}} to silently skip a missing file instead of failing: {{#runtime-import .github/shared/editorial.md}} # required — fails if missing {{#runtime-import? .github/shared/optional.md}} # optional — skipped if missing Paths resolve within .github , with or without the .github/ prefix ( .github/shared/editorial.md and shared/editorial.md are the same file).

Compile-time imports may follow symlinks only if the target stays inside the allowed folder ( .github , or .agents for /.agents/ imports). The allowed folder itself must not be a symlink, and dangling symlinks or symlinked parents that escape it are rejected. File reads stay confined to the folder selected during resolution, even with inlined-imports: true or if symlinks change after validation. Nested folders named .github or .agents do not change this boundary.

See Runtime Imports for line ranges and security details. Shared Workflow Components Section titled “Shared Workflow Components” Files without a trigger event are shared workflow components. They are validated, importable by other workflows, and not compiled into standalone GitHub Actions. Shared components may also define import-safe on keys ( skip-if-match , skip-if-no-match , skip-roles , skip-bots , github-token , github-app ) plus the top-level ambient-folders field.

Comment-only frontmatter counts as present and yields an empty frontmatter map. Only missing or whitespace-only frontmatter is rejected. If you often import the same pair together, bundle them into one shared file: --- on : schedule : daily engine : copilot imports : - shared/reporting-otlp.md --- shared/reporting-otlp.md combines shared/reporting.md and shared/otlp.md for telemetry-enabled reporting workflows. Shared OTLP configuration can reference whole values such as ${{ github.aw.metadata.<key> }} in observability.otlp.attributes and observability.otlp.resource-attributes .

These resolve at compile time against each importing root workflow’s metadata map, so callers need not pass them as inputs. Only simple, existing keys work, and only explicitly selected values are exported. Import Schema ( import-schema ) Section titled “Import Schema (import-schema)” import-schema declares a typed parameter contract. Callers pass values via with , and the compiler validates them and substitutes them into the frontmatter and body. --- # shared/deploy.md — no 'on:' field, shared component only import-schema : region : type : string required : true environment : type : choice options : [ staging , production ] required : true count : type : number default : 10 languages : type : array items : type : string required : true config : type : object description : Configuration object properties : project : type : string required : true timeout : type : number default : 30 --- Deploy ${{ github.aw.import-inputs.count }} items to ${{ github.aw.import-inputs.region }}.

Project: ${{ github.aw.import-inputs.config.project }}. Languages: ${{ github.aw.import-inputs.languages }}. Supported types Section titled “Supported types” Type Description Extra fields string Plain text value — number Numeric value — integer Whole numeric value minimum , maximum boolean true / false — choice One of a fixed set of strings options: [...] array Ordered list of values items.type (element type) object Key/value map properties (one level deep) Each field supports required: true and an optional default value.

Numeric and integer fields may set inclusive minimum and maximum bounds. Accessing inputs in shared workflows Section titled “Accessing inputs in shared workflows” Use ${{ github.aw.import-inputs.<key> }} for top-level values and dotted notation for object sub-fields (e.g. ${{ github.aw.import-inputs.config.project }} ). Substitution applies to frontmatter and body, so inputs can drive any field, such as mcp-servers or runtimes .

Values used in prompt bodies must be non-secret; environment filtering cannot identify credentials deliberately supplied as input text. Calling a parameterized shared workflow Section titled “Calling a parameterized shared workflow” --- on : issues engine : copilot imports : - uses : shared/deploy.md with : region : us-east-1 environment : staging count : 5 languages : [ " go " , " typescript " ] config : project : release-dashboard timeout : 60 --- The compiler validates required fields, choice options, array element types, and object properties .

Unknown keys are compile-time errors. Path Resolution Section titled “Path Resolution” Imports resolve by path format: Relative paths (default) Section titled “Relative paths (default)” Paths without a .github/ , / , or owner/repo/ prefix resolve relative to the importing workflow’s directory ( .github/workflows/ by default). --- 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/) --- Repo-root-relative paths Section titled “Repo-root-relative paths” Paths starting with .github/ or / resolve from the repository root.

Absolute paths

The rest of this page is on the live site.