Templating | GitHub Agentic Workflows
Skip to main content Templating Agentic workflows support four templating and substitution mechanisms: GitHub Actions expressions in frontmatter or markdown, conditional markdown blocks, compile-time imports , and runtime imports for local files. GitHub Actions Expressions Section titled “GitHub Actions Expressions” Agentic workflows restrict expressions in markdown content to an allowlist. Repository-local workflow and runtime-import files are author sources.
Prompt assembly does not fetch external content. Note : These restrictions apply to markdown content. YAML frontmatter can still use secrets for workflow configuration, but secret-backed environment variables cannot be selected as prompt bindings. Markdown allows event properties ( github.event.* ), repository context ( github.actor , github.owner , github.repository , github.server_url , github.workspace ), run metadata ( github.run_id , github.run_number , github.job , github.workflow ), and pattern expressions such as needs.* , steps.* , and github.event.inputs.* .
Activation Outputs Section titled “Activation Outputs” Use steps.sanitized.outputs.text , .title , or .body in markdown prompts to access sanitized event content. text includes the full sanitized context (title + body for issues and PRs, body for comments), while title and body expose those fields individually. Other activation outputs such as comment_id , comment_repo , and slash_command are available as needs.activation.outputs.* in downstream jobs, not in the markdown prompt itself.
Prohibited Expressions Section titled “Prohibited Expressions” All other expressions are disallowed, including secrets.* , vars.* , and complex functions like toJson() or fromJson() . Author Expression Bindings Section titled “Author Expression Bindings” The main workflow and local runtime-import files support env.* expressions, including comparisons and defaults such as ${{ env.LOG_LEVEL || 'info' }} . The compiler creates explicit bindings evaluated by GitHub Actions; this is not access to the runner’s entire environment.
Secret-backed environment variables and known credential variables cannot be bound into prompts, including in non-strict mode. An explicitly selected non-secret environment variable may be configured from vars.* in YAML frontmatter, for example LOG_LEVEL: ${{ vars.LOG_LEVEL || 'info' }} , then referenced as ${{ env.LOG_LEVEL }} in an author source. The direct vars.* prompt restriction does not prohibit this configuration alias.
Authors must not store credentials in configuration variables or select credential-bearing values as prompt bindings. Local runtime imports have the same author expression capabilities as the main workflow, including nested local imports within the permitted folders. Evaluated values remain literal data and cannot introduce additional imports or directives. Remote runtime imports are rejected, even when optional or nested in local files.
Prompt Execution and Credentials Section titled “Prompt Execution and Credentials” Activation-job prompt creation, interpolation, and substitution use pinned actions/github-script actions. Their default GitHub token is replaced with the non-secret no-authentication placeholder because the action requires a nonempty token. Before loading prompt modules, the shared setup_prompt_globals.cjs helper removes environment variables outside its explicit bindings and non-secret runner/context allowlist, including inherited tokens and Node startup options.
The compiler passes selected binding names through GH_AW_PROMPT_ENV , keeping environment filtering and global setup out of generated lock-file scripts. Prompt modules receive core and context , not an authenticated API client. Existing shell validation and printing steps remain shell steps. Environment cleanup occurs after the action starts, not before Node startup. It is not process-startup, filesystem, or runner isolation; authors must not place credentials in prompt files, inputs, or custom job outputs.
Expression safety is validated during compilation. Unauthorized expressions produce errors like: error: unauthorized expressions: [secrets.TOKEN, vars.MY_VAR]. allowed: [github.repository, github.actor, github.workflow, ...] Conditional Markdown Section titled “Conditional Markdown” Include or exclude prompt sections based on boolean expressions using {{#if ...}} ... {{/if}} blocks. Only directives written in workflow templates or imported prompt sources execute.
Substituted event content and job outputs remain literal, including template markers inside inline code or fenced code blocks. Template examples written inside code regions are also preserved. Values referenced by author-written conditions still determine which branch is selected. Work-queue assignments selected from event payloads are JSON-encoded with explicit data-only guidance. Their rendered work-claim envelopes remain literal through directive processing and deferred substitution, preserving claim-completion guidance.
The data-only instruction is model guidance, not a guarantee against semantic prompt injection. Syntax Section titled “Syntax” {{#if expression}} Content to include if expression is truthy {{/if}} The compiler automatically wraps expressions with ${{ }} for GitHub Actions evaluation. For example, {{#if github.event.issue.number}} becomes {{#if ${{ github.event.issue.number }} }} . Comparisons require an operator, for example {{#if experiments.reasoning_depth == 'iterative'}} .
Invalid expressions or active conditions in the main workflow or local runtime imports fail compilation; they do not disable substitution of other prompt expressions. Syntactically invalid implicit conditions inside code regions are treated as literal examples; valid conditions and explicit GitHub Actions expressions still receive bindings. Falsy values: false , 0 , null , undefined , "" (empty string) Truthy values: Everything else Example Section titled “Example” --- on : issues : types : [ opened ] --- # Issue Analysis Analyze issue #${{ github.event.issue.number }}. {{#if github.event.issue.number}} ## Issue-Specific Analysis You are analyzing issue #${{ github.event.issue.number }}. {{/if}} {{#if github.event.pull_request.number}} ## Pull Request Analysis You are analyzing PR #${{ github.event.pull_request.number }}. {{/if}} Limitations Section titled “Limitations” Conditions support allowlisted expressions, including comparisons and defaults.
Alternative branches use {{#elseif expression}} and {{#else}} . Nested conditional blocks, variable assignments, and loops are not supported. Runtime Imports Section titled “Runtime Imports” Runtime imports include local content in workflow prompts at runtime (unlike compile-time imports ). File paths are restricted to .github or explicit .agents/ paths. Use {{#runtime-import target}} or {{#runtime-import? target}} for optional local files.
URLs and network-path targets are not supported. Source Capabilities Section titled “Source Capabilities” Source Processing capabilities Prompt-tree trust Locally assembled system and user prompts Imports, author-written directives, and compiler-selected expression bindings author Repository-local runtime-import files Same author capabilities, including nested imports within permitted folders author These labels describe source capabilities, not the safety of every interpolated value or descendant.
See prompt provenance artifacts for the tree format. Macro Syntax Section titled “Macro Syntax” Use {{#runtime-import filepath}} to include file content at runtime. Use {{#runtime-import? filepath}} when the file is optional. All file paths resolve within .github , with or without the .github/ prefix: --- on : issues engine : copilot --- # Code Review Agent Follow these coding guidelines: {{#runtime-import coding-standards.md}} <!-- Same as: {{#runtime-import .github/coding-standards.md}} --> Review the code changes and provide feedback.
Line range ext
The rest of this page is on the live site.