From d821007dbcf233668db49ae500ebe7813d93ce52 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 11:05:07 +0000 Subject: [PATCH] Sync github-agentic-workflows.md with v0.68.3 Document five schema fields present in code but missing from instructions: - pre-agent-steps: steps running immediately before AI execution (after setup) - import-schema: typed input definitions for importable shared workflows - private: prevent workflow from being shared via gh aw add - redirect: workflow relocation path for gh aw update - resources: additional files fetched alongside workflow by gh aw add Also document object form of imports (path/uses + with/inputs) for passing inputs to shared workflows that declare import-schema. Co-Authored-By: Claude Sonnet 4.6 --- .github/aw/github-agentic-workflows.md | 46 ++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index e989c9699c5..1dc7372966e 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -211,6 +211,7 @@ The YAML frontmatter supports these fields: - **`name:`** - Workflow name (string) - **`pre-steps:`** - Custom workflow steps to run at the very beginning of the agent job, before checkout (object). Use for token minting or setup that must happen before the repository is checked out. Step outputs are available via `${{ steps..outputs. }}` and can be referenced in `checkout.github-token` to avoid masked-value cross-job boundary issues. Same security restrictions apply as for `steps:`. - **`steps:`** - Custom workflow steps before AI execution (object). **Security Notice**: Custom steps run OUTSIDE the firewall sandbox with standard GitHub Actions security but NO network egress controls. Use only for deterministic data preparation, not agentic compute. **Secrets restriction**: Using `${{ secrets.* }}` expressions (other than `secrets.GITHUB_TOKEN`) in custom steps is an error in strict mode and a warning otherwise — move secret-dependent operations to a separate job outside the agent job. +- **`pre-agent-steps:`** - Custom workflow steps to run immediately before AI execution, after all initialization and setup steps (runtimes, MCP servers, tools) have been configured (object or array). Use when preparation requires the full environment to be ready. Same security restrictions apply as for `steps:`. - **`post-steps:`** - Custom workflow steps after AI execution (object). **Security Notice**: Post-execution steps run OUTSIDE the firewall sandbox. Use only for deterministic cleanup, artifact uploads, or notifications—not agentic compute or untrusted AI execution. Same secrets restriction applies as for `steps:`. - **`environment:`** - Environment that the job references for protection rules (string or object) - **`container:`** - Container to run job steps in (string or object) @@ -292,9 +293,41 @@ The YAML frontmatter supports these fields: - The frontmatter hash covers the entire markdown body when enabled, so any content change invalidates the hash - **Required for repository rulesets**: Workflows used as required status checks in repository rulesets run without access to repository files at runtime. Set `inlined-imports: true` to bundle all imported content at compile time to avoid "Runtime import file not found" errors - **Constraint**: Cannot be combined with agent file imports (`.github/agents/` files). Remove any custom agent file imports before enabling +- **`import-schema:`** - Define typed input parameters for this shared workflow (object). Use when other workflows import this one via the `uses:`/`with:` syntax (see [Imports Field](#imports-field)). + - Parameters are accessible inside the shared workflow via `${{ github.aw.import-inputs. }}` expressions + - Object inputs (type: `object`) allow one-level deep sub-fields: `${{ github.aw.import-inputs.. }}` + - Fields per parameter: + - `type:` - Input type: `string`, `number`, `boolean`, `choice`, or `array` + - `description:` - Human-readable parameter description + - `required:` - Whether the input is required when imported (default: `false`) + - `default:` - Default value when not provided + - `options:` - Allowed values for `choice` type inputs + - Example: + + ```yaml + import-schema: + environment: + type: choice + description: "Target environment" + options: [dev, staging, prod] + required: true + max-issues: + type: number + default: 5 + ``` + - **`mcp-servers:`** - MCP (Model Context Protocol) server definitions (object) - Defines custom MCP servers for additional tools beyond built-in ones +- **`private:`** - Mark this workflow as private, preventing it from being shared via `gh aw add` (boolean, default: `false`) + - Example: `private: true` + +- **`redirect:`** - Workflow relocation path for updates (string). When present, `gh aw update` follows this location and rewrites the `source:` field. Format: `owner/repo/path@ref` or full GitHub URL. + - Example: `redirect: "org/agentics/workflows/my-workflow-v2.md@main"` + +- **`resources:`** - Additional workflow or action files fetched alongside this workflow when running `gh aw add` (array). Entries are relative paths from the same directory to `.md` or `.yml`/`.yaml` files. + - Example: `resources: [shared/tool-setup.md, shared/mcp/tavily.md]` + - **`tracker-id:`** - Optional identifier to tag all created assets (string) - Must be at least 8 characters and contain only alphanumeric characters, hyphens, and underscores - This identifier is inserted in the body/description of all created assets (issues, discussions, comments, pull requests) @@ -2184,6 +2217,19 @@ imports: --- ``` +**Object form with inputs** — Use `path:`/`uses:` + `with:`/`inputs:` to pass values to shared workflows that define an `import-schema:`: + +```yaml +imports: + - path: shared/tool-setup.md + with: + environment: staging + max-issues: 3 + - uses: shared/security-notice.md # 'uses' is an alias for 'path' +``` + +Inside the imported workflow, access values via `${{ github.aw.import-inputs. }}`. + ### Import File Structure Import files are in `.github/workflows/shared/` and can contain: