{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://github.com/github/gh-aw/schemas/main_workflow_schema.json", "title": "GitHub Agentic Workflow Schema", "description": "JSON Schema for validating agentic workflow frontmatter configuration", "version": "1.0.0", "type": "object", "required": ["on"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Workflow name that appears in the GitHub Actions interface. If not specified, defaults to the filename without extension.", "examples": ["Copilot Agent PR Analysis", "Dev Hawk", "Smoke Claude"] }, "description": { "type": "string", "maxLength": 10000, "description": "Optional workflow description that is rendered as a comment in the generated GitHub Actions YAML file (.lock.yml)", "examples": ["Quickstart for using the GitHub Actions library"] }, "source": { "type": "string", "description": "Optional source reference indicating where this workflow was added from. Format: owner/repo/path@ref (e.g., githubnext/agentics/workflows/ci-doctor.md@v1.0.0). Rendered as a comment in the generated lock file.", "examples": ["githubnext/agentics/workflows/ci-doctor.md", "githubnext/agentics/workflows/daily-perf-improver.md@1f181b37d3fe5862ab590648f25a292e345b5de6"] }, "tracker-id": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Optional tracker identifier to tag all created assets (issues, discussions, comments, pull requests). Must be at least 8 characters and contain only alphanumeric characters, hyphens, and underscores. This identifier will be inserted in the body/description of all created assets to enable searching and retrieving assets associated with this workflow.", "examples": ["workflow-2024-q1", "team-alpha-bot", "security_audit_v2"] }, "labels": { "type": "array", "description": "Optional array of labels to categorize and organize workflows. Labels can be used to filter workflows in status/list commands.", "items": { "type": "string", "minLength": 1 }, "examples": [ ["automation", "security"], ["docs", "maintenance"], ["ci", "testing"] ] }, "metadata": { "type": "object", "description": "Optional metadata field for storing custom key-value pairs compatible with the custom agent spec. Key names are limited to 64 characters, and values are limited to 1024 characters.", "patternProperties": { "^.{1,64}$": { "type": "string", "maxLength": 1024, "description": "Metadata value (maximum 1024 characters)" } }, "additionalProperties": false, "examples": [ { "author": "John Doe", "version": "1.0.0", "category": "automation" } ] }, "imports": { "type": "array", "description": "Optional 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.", "items": { "oneOf": [ { "type": "string", "description": "Workflow specification in format owner/repo/path@ref. Markdown files under .github/agents/ are treated as agent configuration files." }, { "type": "object", "description": "Import specification with path and optional inputs", "required": ["path"], "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Workflow specification in format owner/repo/path@ref. Markdown files under .github/agents/ are treated as agent configuration files." }, "inputs": { "type": "object", "description": "Input values to pass to the imported workflow. Keys are input names declared in the imported workflow's inputs section, values can be strings or expressions.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } } ] }, "examples": [ ["shared/jqschema.md", "shared/reporting.md"], ["shared/mcp/gh-aw.md", "shared/jqschema.md", "shared/reporting.md"], ["../instructions/documentation.instructions.md"], [".github/agents/my-agent.md"], [ { "path": "shared/discussions-data-fetch.md", "inputs": { "count": 50 } } ] ] }, "resources": { "type": "array", "description": "Optional list of additional workflow or action files that should be fetched alongside this workflow when running 'gh aw add'. Entries are relative paths (from the same directory as this workflow in the source repository) to agentic workflow .md files or GitHub Actions .yml/.yaml files. GitHub Actions expression syntax (${{) is not allowed in resource paths.", "items": { "type": "string", "description": "Relative path to a workflow .md file or action .yml/.yaml file. Must be a static path; GitHub Actions expression syntax (${{) is not allowed.", "not": { "pattern": "\\$\\{\\{" } }, "examples": [["triage-issue.md", "label-issue.md"], ["my-custom-action.yml"], ["shared/helper-action.yml", "close-stale.md"]] }, "inlined-imports": { "type": "boolean", "default": false, "description": "If true, inline all imports (including those without inputs) at compilation time in the generated lock.yml instead of using runtime-import macros. When enabled, the frontmatter hash covers the entire markdown body so any change to the content will invalidate the hash.", "examples": [true, false] }, "on": { "description": "Workflow triggers that define when the agentic workflow should run. Supports standard GitHub Actions trigger events plus special command triggers for /commands (required)", "examples": [ { "issues": { "types": ["opened"] } }, { "pull_request": { "types": ["opened", "synchronize"] } }, "workflow_dispatch", { "schedule": "daily at 9am" }, "/my-bot" ], "oneOf": [ { "type": "string", "minLength": 1, "description": "Simple trigger event name (e.g., 'push', 'issues', 'pull_request', 'discussion', 'schedule', 'fork', 'create', 'delete', 'public', 'watch', 'workflow_call'), schedule shorthand (e.g., 'daily', 'weekly'), or slash command shorthand (e.g., '/my-bot' expands to slash_command + workflow_dispatch)", "examples": ["push", "issues", "workflow_dispatch", "daily", "/my-bot"] }, { "type": "object", "description": "Complex trigger configuration with event-specific filters and options", "properties": { "slash_command": { "description": "Special slash command trigger for /command workflows (e.g., '/my-bot' in issue comments). Creates conditions to match slash commands automatically. Note: Can be combined with issues/pull_request events if those events only use 'labeled' or 'unlabeled' types.", "oneOf": [ { "type": "null", "description": "Null command configuration - defaults to using the workflow filename (without .md extension) as the command name" }, { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Command name as a string (shorthand format, e.g., 'customname' for '/customname' triggers). Command names must not start with '/' as the slash is automatically added when matching commands." }, { "type": "object", "description": "Command configuration object with custom command name", "properties": { "name": { "oneOf": [ { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Single command name for slash commands (e.g., 'helper-bot' for '/helper-bot' triggers). Command names must not start with '/' as the slash is automatically added when matching commands. Defaults to workflow filename without .md extension if not specified." }, { "type": "array", "minItems": 1, "description": "Array of command names that trigger this workflow (e.g., ['cmd.add', 'cmd.remove'] for '/cmd.add' and '/cmd.remove' triggers). Each command name must not start with '/'.", "items": { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Command name without leading slash" }, "maxItems": 25 } ], "description": "Name of the slash command that triggers the workflow (e.g., '/help', '/analyze'). Used for comment-based workflow activation." }, "events": { "description": "Events where the command should be active. Default is all comment-related events ('*'). Use GitHub Actions event names.", "oneOf": [ { "type": "string", "description": "Single event name or '*' for all events. Use GitHub Actions event names: 'issues', 'issue_comment', 'pull_request_comment', 'pull_request', 'pull_request_review_comment', 'discussion', 'discussion_comment'.", "enum": ["*", "issues", "issue_comment", "pull_request_comment", "pull_request", "pull_request_review_comment", "discussion", "discussion_comment"] }, { "type": "array", "minItems": 1, "description": "Array of event names where the command should be active (requires at least one). Use GitHub Actions event names.", "items": { "type": "string", "description": "GitHub Actions event name.", "enum": ["*", "issues", "issue_comment", "pull_request_comment", "pull_request", "pull_request_review_comment", "discussion", "discussion_comment"] }, "maxItems": 25 } ] } }, "additionalProperties": false } ] }, "command": { "description": "DEPRECATED: Use 'slash_command' instead. Special command trigger for /command workflows (e.g., '/my-bot' in issue comments). Creates conditions to match slash commands automatically.", "oneOf": [ { "type": "null", "description": "Null command configuration - defaults to using the workflow filename (without .md extension) as the command name" }, { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Command name as a string (shorthand format, e.g., 'customname' for '/customname' triggers). Command names must not start with '/' as the slash is automatically added when matching commands." }, { "type": "object", "description": "Command configuration object with custom command name", "properties": { "name": { "oneOf": [ { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Custom command name for slash commands (e.g., 'helper-bot' for '/helper-bot' triggers). Command names must not start with '/' as the slash is automatically added when matching commands. Defaults to workflow filename without .md extension if not specified." }, { "type": "array", "minItems": 1, "description": "Array of command names that trigger this workflow (e.g., ['cmd.add', 'cmd.remove'] for '/cmd.add' and '/cmd.remove' triggers). Each command name must not start with '/'.", "items": { "type": "string", "minLength": 1, "pattern": "^[^/]", "description": "Command name without leading slash" }, "maxItems": 25 } ], "description": "Name of the slash command that triggers the workflow (e.g., '/deploy', '/test'). Used for command-based workflow activation." }, "events": { "description": "Events where the command should be active. Default is all comment-related events ('*'). Use GitHub Actions event names.", "oneOf": [ { "type": "string", "description": "Single event name or '*' for all events. Use GitHub Actions event names: 'issues', 'issue_comment', 'pull_request_comment', 'pull_request', 'pull_request_review_comment', 'discussion', 'discussion_comment'.", "enum": ["*", "issues", "issue_comment", "pull_request_comment", "pull_request", "pull_request_review_comment", "discussion", "discussion_comment"] }, { "type": "array", "minItems": 1, "description": "Array of event names where the command should be active (requires at least one). Use GitHub Actions event names.", "items": { "type": "string", "description": "GitHub Actions event name.", "enum": ["*", "issues", "issue_comment", "pull_request_comment", "pull_request", "pull_request_review_comment", "discussion", "discussion_comment"] }, "maxItems": 25 } ] } }, "additionalProperties": false } ] }, "label_command": { "description": "On Label Command trigger: fires when a specific label is added to an issue, pull request, or discussion. The triggering label is automatically removed at workflow start so it can be applied again to re-trigger. Use the 'events' field to restrict which item types (issues, pull_request, discussion) activate the trigger.", "oneOf": [ { "type": "string", "minLength": 1, "description": "Label name as a string (shorthand format). The workflow fires when this label is added to any supported item type (issue, pull request, or discussion)." }, { "type": "object", "description": "Label command configuration object with label name(s) and optional event filtering.", "properties": { "name": { "oneOf": [ { "type": "string", "minLength": 1, "description": "Single label name that acts as a command (e.g., 'deploy' triggers the workflow when the 'deploy' label is added)." }, { "type": "array", "minItems": 1, "description": "Array of label names \u2014 any of these labels will trigger the workflow.", "items": { "type": "string", "minLength": 1, "description": "A label name" }, "maxItems": 25 } ], "description": "Label name(s) that trigger the workflow when added to an issue, pull request, or discussion." }, "names": { "oneOf": [ { "type": "string", "minLength": 1, "description": "Single label name." }, { "type": "array", "minItems": 1, "description": "Array of label names \u2014 any of these labels will trigger the workflow.", "items": { "type": "string", "minLength": 1, "description": "A label name" }, "maxItems": 25 } ], "description": "Alternative to 'name': label name(s) that trigger the workflow." }, "events": { "description": "Item types where the label-command trigger should be active. Default is all supported types: issues, pull_request, discussion.", "oneOf": [ { "type": "string", "description": "Single item type or '*' for all types.", "enum": ["*", "issues", "pull_request", "discussion"] }, { "type": "array", "minItems": 1, "description": "Array of item types where the trigger is active.", "items": { "type": "string", "description": "Item type.", "enum": ["*", "issues", "pull_request", "discussion"] }, "maxItems": 3 } ] }, "remove_label": { "type": "boolean", "description": "Whether to automatically remove the triggering label after the workflow starts. Defaults to true. Set to false to keep the label on the item and skip the label-removal step. When false, the issues:write and discussions:write permissions required for label removal are also omitted." } }, "additionalProperties": false } ] }, "push": { "description": "Push event trigger that runs the workflow when code is pushed to the repository", "type": "object", "additionalProperties": false, "properties": { "branches": { "type": "array", "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.", "description": "Branches to filter on", "items": { "type": "string" } }, "branches-ignore": { "type": "array", "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.", "description": "Branches to ignore", "items": { "type": "string" } }, "paths": { "type": "array", "$comment": "Mutually exclusive with paths-ignore. GitHub Actions requires only one to be specified.", "description": "Paths to filter on", "items": { "type": "string" } }, "paths-ignore": { "type": "array", "$comment": "Mutually exclusive with paths. GitHub Actions requires only one to be specified.", "description": "Paths to ignore", "items": { "type": "string" } }, "tags": { "type": "array", "description": "List of git tag names or patterns to include for push events (supports wildcards)", "items": { "type": "string" } }, "tags-ignore": { "type": "array", "description": "List of git tag names or patterns to exclude from push events (supports wildcards)", "items": { "type": "string" } } }, "oneOf": [ { "required": ["branches"], "not": { "required": ["branches-ignore"] } }, { "required": ["branches-ignore"], "not": { "required": ["branches"] } }, { "not": { "anyOf": [ { "required": ["branches"] }, { "required": ["branches-ignore"] } ] } } ], "allOf": [ { "oneOf": [ { "required": ["paths"], "not": { "required": ["paths-ignore"] } }, { "required": ["paths-ignore"], "not": { "required": ["paths"] } }, { "not": { "anyOf": [ { "required": ["paths"] }, { "required": ["paths-ignore"] } ] } } ] } ] }, "pull_request": { "description": "Pull request event trigger that runs the workflow when pull requests are created, updated, or closed", "type": "object", "properties": { "types": { "type": "array", "description": "Pull request event types to trigger on. Note: 'converted_to_draft' and 'ready_for_review' represent state transitions (events) rather than states. While technically valid to listen for both, consider if you need to handle both transitions or just one.", "$comment": "converted_to_draft and ready_for_review are logically opposite state transitions. Using both may indicate unclear intent.", "items": { "type": "string", "enum": [ "assigned", "unassigned", "labeled", "unlabeled", "opened", "edited", "closed", "reopened", "synchronize", "converted_to_draft", "locked", "unlocked", "enqueued", "dequeued", "milestoned", "demilestoned", "ready_for_review", "review_requested", "review_request_removed", "auto_merge_enabled", "auto_merge_disabled" ] } }, "branches": { "type": "array", "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.", "description": "Branches to filter on", "items": { "type": "string" } }, "branches-ignore": { "type": "array", "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.", "description": "Branches to ignore", "items": { "type": "string" } }, "paths": { "type": "array", "$comment": "Mutually exclusive with paths-ignore. GitHub Actions requires only one to be specified.", "description": "Paths to filter on", "items": { "type": "string" } }, "paths-ignore": { "type": "array", "$comment": "Mutually exclusive with paths. GitHub Actions requires only one to be specified.", "description": "Paths to ignore", "items": { "type": "string" } }, "draft": { "type": "boolean", "description": "Filter by draft pull request state. Set to false to exclude draft PRs, true to include only drafts, or omit to include both" }, "forks": { "oneOf": [ { "type": "string", "description": "Single fork pattern (e.g., '*' for all forks, 'org/*' for org glob, 'org/repo' for exact match)" }, { "type": "array", "description": "List of allowed fork repositories with glob support (e.g., 'org/repo', 'org/*', '*' for all forks)", "items": { "type": "string", "description": "Repository pattern with optional glob support" } } ], "description": "When true, allows workflow to run on pull requests from forked repositories. Security consideration: fork PRs have limited permissions." }, "names": { "oneOf": [ { "type": "string", "description": "Single label name to filter labeled/unlabeled events (e.g., 'bug')" }, { "type": "array", "description": "List of label names to filter labeled/unlabeled events. Only applies when 'labeled' or 'unlabeled' is in the types array", "items": { "type": "string", "description": "Label name" }, "minItems": 1, "maxItems": 25 } ], "description": "Array of pull request type names that trigger the workflow. Filters workflow execution to specific PR categories." } }, "additionalProperties": false, "oneOf": [ { "required": ["branches"], "not": { "required": ["branches-ignore"] } }, { "required": ["branches-ignore"], "not": { "required": ["branches"] } }, { "not": { "anyOf": [ { "required": ["branches"] }, { "required": ["branches-ignore"] } ] } } ], "allOf": [ { "oneOf": [ { "required": ["paths"], "not": { "required": ["paths-ignore"] } }, { "required": ["paths-ignore"], "not": { "required": ["paths"] } }, { "not": { "anyOf": [ { "required": ["paths"] }, { "required": ["paths-ignore"] } ] } } ] } ] }, "issues": { "description": "Issues event trigger that runs when repository issues are created, updated, or managed", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of issue events", "items": { "type": "string", "enum": ["opened", "edited", "deleted", "transferred", "pinned", "unpinned", "closed", "reopened", "assigned", "unassigned", "labeled", "unlabeled", "locked", "unlocked", "milestoned", "demilestoned", "typed", "untyped"] } }, "names": { "oneOf": [ { "type": "string", "description": "Single label name to filter labeled/unlabeled events (e.g., 'bug')" }, { "type": "array", "description": "List of label names to filter labeled/unlabeled events. Only applies when 'labeled' or 'unlabeled' is in the types array", "items": { "type": "string", "description": "Label name" }, "minItems": 1, "maxItems": 25 } ], "description": "Array of issue type names that trigger the workflow. Filters workflow execution to specific issue categories." }, "lock-for-agent": { "type": "boolean", "description": "Whether to lock the issue for the agent when the workflow runs (prevents concurrent modifications)" } } }, "issue_comment": { "description": "Issue comment event trigger", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of issue comment events", "items": { "type": "string", "enum": ["created", "edited", "deleted"] } }, "lock-for-agent": { "type": "boolean", "description": "Whether to lock the parent issue for the agent when the workflow runs (prevents concurrent modifications)" } } }, "discussion": { "description": "Discussion event trigger that runs the workflow when repository discussions are created, updated, or managed", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of discussion events", "items": { "type": "string", "enum": ["created", "edited", "deleted", "transferred", "pinned", "unpinned", "labeled", "unlabeled", "locked", "unlocked", "category_changed", "answered", "unanswered"] } } } }, "discussion_comment": { "description": "Discussion comment event trigger that runs the workflow when comments on discussions are created, updated, or deleted", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of discussion comment events", "items": { "type": "string", "enum": ["created", "edited", "deleted"] } } } }, "schedule": { "description": "Scheduled trigger events using fuzzy schedules or standard cron expressions. Supports shorthand string notation (e.g., 'daily', 'daily around 2pm') or array of schedule objects. Fuzzy schedules automatically distribute execution times to prevent load spikes.", "oneOf": [ { "type": "string", "minLength": 1, "description": "Shorthand schedule string using fuzzy or cron format. Examples: 'daily', 'daily around 14:00', 'daily between 9:00 and 17:00', 'weekly', 'weekly on monday', 'weekly on friday around 5pm', 'hourly', 'every 2h', 'every 10 minutes', '0 9 * * 1'. Fuzzy schedules distribute execution times to prevent load spikes. For fixed times, use standard cron syntax. Minimum interval is 5 minutes." }, { "type": "array", "minItems": 1, "description": "Array of schedule objects with cron expressions (standard cron or fuzzy format)", "items": { "type": "object", "properties": { "cron": { "type": "string", "description": "Cron expression using standard format (e.g., '0 9 * * 1') or fuzzy format (e.g., 'daily', 'daily around 14:00', 'daily between 9:00 and 17:00', 'weekly', 'weekly on monday', 'weekly on friday around 5pm', 'hourly', 'every 2h', 'every 10 minutes'). Fuzzy formats support: daily/weekly schedules with optional time windows, hourly intervals with scattered minutes, interval schedules (minimum 5 minutes), short duration units (m/h/d/w), and UTC timezone offsets (utc+N or utc+HH:MM)." }, "timezone": { "type": "string", "description": "Optional IANA timezone string for timezone-aware scheduling (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo', 'UTC'). When set, the cron expression is interpreted in the specified timezone instead of UTC." } }, "required": ["cron"], "additionalProperties": false }, "maxItems": 10 } ] }, "workflow_dispatch": { "description": "Manual workflow dispatch trigger", "oneOf": [ { "type": "null", "description": "Simple workflow dispatch trigger" }, { "type": "object", "additionalProperties": false, "properties": { "inputs": { "type": "object", "description": "Input parameters for manual dispatch", "maxProperties": 25, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "description": "Input description" }, "required": { "type": "boolean", "description": "Whether input is required" }, "default": { "description": "Default value for the input. Type depends on the input type: string for string/choice/environment, boolean for boolean, number for number", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] }, "type": { "type": "string", "enum": ["string", "choice", "boolean", "number", "environment"], "description": "Input type. GitHub Actions supports: string (default), boolean, choice (string with predefined options), number, and environment (string referencing a GitHub environment)" }, "options": { "type": "array", "description": "Options for choice type", "items": { "type": "string" } } } } } } } ] }, "workflow_run": { "description": "Workflow run trigger", "type": "object", "additionalProperties": false, "properties": { "workflows": { "type": "array", "description": "List of workflows to trigger on", "items": { "type": "string" } }, "types": { "type": "array", "description": "Types of workflow run events", "items": { "type": "string", "enum": ["completed", "requested", "in_progress"] } }, "branches": { "type": "array", "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.", "description": "Branches to filter on", "items": { "type": "string" } }, "branches-ignore": { "type": "array", "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.", "description": "Branches to ignore", "items": { "type": "string" } } }, "oneOf": [ { "required": ["branches"], "not": { "required": ["branches-ignore"] } }, { "required": ["branches-ignore"], "not": { "required": ["branches"] } }, { "not": { "anyOf": [ { "required": ["branches"] }, { "required": ["branches-ignore"] } ] } } ] }, "release": { "description": "Release event trigger", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of release events", "items": { "type": "string", "enum": ["published", "unpublished", "created", "edited", "deleted", "prereleased", "released"] } } } }, "pull_request_review_comment": { "description": "Pull request review comment event trigger", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of pull request review comment events", "items": { "type": "string", "enum": ["created", "edited", "deleted"] } } } }, "branch_protection_rule": { "description": "Branch protection rule event trigger that runs when branch protection rules are changed", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of branch protection rule events", "items": { "type": "string", "enum": ["created", "edited", "deleted"] } } } }, "check_run": { "description": "Check run event trigger that runs when a check run is created, rerequested, completed, or has a requested action", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of check run events", "items": { "type": "string", "enum": ["created", "rerequested", "completed", "requested_action"] } } } }, "check_suite": { "description": "Check suite event trigger that runs when check suite activity occurs", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of check suite events", "items": { "type": "string", "enum": ["completed"] } } } }, "create": { "description": "Create event trigger that runs when a Git reference (branch or tag) is created", "oneOf": [ { "type": "null", "description": "Simple create event trigger" }, { "type": "object", "additionalProperties": false } ] }, "delete": { "description": "Delete event trigger that runs when a Git reference (branch or tag) is deleted", "oneOf": [ { "type": "null", "description": "Simple delete event trigger" }, { "type": "object", "additionalProperties": false } ] }, "deployment": { "description": "Deployment event trigger that runs when a deployment is created", "oneOf": [ { "type": "null", "description": "Simple deployment event trigger" }, { "type": "object", "additionalProperties": false } ] }, "deployment_status": { "description": "Deployment status event trigger that runs when a deployment status is updated", "oneOf": [ { "type": "null", "description": "Simple deployment status event trigger" }, { "type": "object", "additionalProperties": false } ] }, "fork": { "description": "Fork event trigger that runs when someone forks the repository", "oneOf": [ { "type": "null", "description": "Simple fork event trigger" }, { "type": "object", "additionalProperties": false } ] }, "gollum": { "description": "Gollum event trigger that runs when someone creates or updates a Wiki page", "oneOf": [ { "type": "null", "description": "Simple gollum event trigger" }, { "type": "object", "additionalProperties": false } ] }, "label": { "description": "Label event trigger that runs when a label is created, edited, or deleted", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of label events", "items": { "type": "string", "enum": ["created", "edited", "deleted"] } } } }, "merge_group": { "description": "Merge group event trigger that runs when a pull request is added to a merge queue", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of merge group events", "items": { "type": "string", "enum": ["checks_requested"] } } } }, "milestone": { "description": "Milestone event trigger that runs when a milestone is created, closed, opened, edited, or deleted", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of milestone events", "items": { "type": "string", "enum": ["created", "closed", "opened", "edited", "deleted"] } } } }, "page_build": { "description": "Page build event trigger that runs when someone pushes to a GitHub Pages publishing source branch", "oneOf": [ { "type": "null", "description": "Simple page build event trigger" }, { "type": "object", "additionalProperties": false } ] }, "public": { "description": "Public event trigger that runs when a repository changes from private to public", "oneOf": [ { "type": "null", "description": "Simple public event trigger" }, { "type": "object", "additionalProperties": false } ] }, "pull_request_target": { "description": "Pull request target event trigger that runs in the context of the base repository (secure for fork PRs)", "type": "object", "properties": { "types": { "type": "array", "description": "List of pull request target event types to trigger on", "items": { "type": "string", "enum": [ "assigned", "unassigned", "labeled", "unlabeled", "opened", "edited", "closed", "reopened", "synchronize", "converted_to_draft", "locked", "unlocked", "enqueued", "dequeued", "review_requested", "review_request_removed", "auto_merge_enabled", "auto_merge_disabled" ] } }, "branches": { "type": "array", "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.", "description": "Branches to filter on", "items": { "type": "string" } }, "branches-ignore": { "type": "array", "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.", "description": "Branches to ignore", "items": { "type": "string" } }, "paths": { "type": "array", "$comment": "Mutually exclusive with paths-ignore. GitHub Actions requires only one to be specified.", "description": "Paths to filter on", "items": { "type": "string" } }, "paths-ignore": { "type": "array", "$comment": "Mutually exclusive with paths. GitHub Actions requires only one to be specified.", "description": "Paths to ignore", "items": { "type": "string" } }, "draft": { "type": "boolean", "description": "Filter by draft pull request state" }, "forks": { "oneOf": [ { "type": "string", "description": "Single fork pattern" }, { "type": "array", "description": "List of allowed fork repositories with glob support", "items": { "type": "string" } } ], "description": "When true, allows workflow to run on pull requests from forked repositories with write permissions. Security consideration: use cautiously as fork PRs run with base repository permissions." } }, "additionalProperties": false, "oneOf": [ { "required": ["branches"], "not": { "required": ["branches-ignore"] } }, { "required": ["branches-ignore"], "not": { "required": ["branches"] } }, { "not": { "anyOf": [ { "required": ["branches"] }, { "required": ["branches-ignore"] } ] } } ], "allOf": [ { "oneOf": [ { "required": ["paths"], "not": { "required": ["paths-ignore"] } }, { "required": ["paths-ignore"], "not": { "required": ["paths"] } }, { "not": { "anyOf": [ { "required": ["paths"] }, { "required": ["paths-ignore"] } ] } } ] } ] }, "pull_request_review": { "description": "Pull request review event trigger that runs when a pull request review is submitted, edited, or dismissed", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of pull request review events", "items": { "type": "string", "enum": ["submitted", "edited", "dismissed"] } } } }, "registry_package": { "description": "Registry package event trigger that runs when a package is published or updated", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of registry package events", "items": { "type": "string", "enum": ["published", "updated"] } } } }, "repository_dispatch": { "description": "Repository dispatch event trigger for custom webhook events", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Custom event types to trigger on", "items": { "type": "string" } } } }, "status": { "description": "Status event trigger that runs when the status of a Git commit changes", "oneOf": [ { "type": "null", "description": "Simple status event trigger" }, { "type": "object", "additionalProperties": false } ] }, "watch": { "description": "Watch event trigger that runs when someone stars the repository", "type": "object", "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of watch events", "items": { "type": "string", "enum": ["started"] } } } }, "workflow_call": { "description": "Workflow call event trigger that allows this workflow to be called by another workflow", "oneOf": [ { "type": "null", "description": "Simple workflow call event trigger" }, { "type": "object", "additionalProperties": false, "properties": { "inputs": { "type": "object", "description": "Input parameters that can be passed to the workflow when it is called", "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the input parameter" }, "required": { "type": "boolean", "description": "Whether the input is required" }, "type": { "type": "string", "enum": ["string", "number", "boolean"], "description": "Type of the input parameter" }, "default": { "description": "Default value for the input parameter" } } } }, "secrets": { "type": "object", "description": "Secrets that can be passed to the workflow when it is called", "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the secret" }, "required": { "type": "boolean", "description": "Whether the secret is required" } } } } } } ] }, "stop-after": { "type": "string", "description": "Time when workflow should stop running. Supports multiple formats: absolute dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.) or relative time deltas (+25h, +3d, +1d12h30m). Maximum values for time deltas: 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not allowed for stop-after; minimum unit is hours 'h'." }, "skip-if-match": { "oneOf": [ { "type": "string", "description": "GitHub search query string to check before running workflow (implies max=1). If the search returns any results, the workflow will be skipped. Query is automatically scoped to the current repository. Example: 'is:issue is:open label:bug'" }, { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "GitHub search query string to check before running workflow. Query is automatically scoped to the current repository." }, "max": { "description": "Maximum number of items that must be matched for the workflow to be skipped. Defaults to 1 if not specified. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "scope": { "type": "string", "enum": ["none"], "description": "Scope for the search query. Set to 'none' to disable the automatic 'repo:owner/repo' scoping, enabling org-wide or cross-repo queries." } }, "additionalProperties": false, "description": "Skip-if-match configuration object with query, maximum match count, and optional scope. For custom authentication use the top-level on.github-token or on.github-app fields." } ], "description": "Conditionally skip workflow execution when a GitHub search query has matches. Can be a string (query only, implies max=1) or an object with 'query', optional 'max', and 'scope' fields. Use top-level on.github-token or on.github-app for custom authentication." }, "skip-if-no-match": { "oneOf": [ { "type": "string", "description": "GitHub search query string to check before running workflow (implies min=1). If the search returns no results, the workflow will be skipped. Query is automatically scoped to the current repository. Example: 'is:pr is:open label:ready-to-deploy'" }, { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "GitHub search query string to check before running workflow. Query is automatically scoped to the current repository." }, "min": { "type": "integer", "minimum": 1, "description": "Minimum number of items that must be matched for the workflow to proceed. Defaults to 1 if not specified." }, "scope": { "type": "string", "enum": ["none"], "description": "Scope for the search query. Set to 'none' to disable the automatic 'repo:owner/repo' scoping, enabling org-wide or cross-repo queries." } }, "additionalProperties": false, "description": "Skip-if-no-match configuration object with query, minimum match count, and optional scope. For custom authentication use the top-level on.github-token or on.github-app fields." } ], "description": "Conditionally skip workflow execution when a GitHub search query has no matches (or fewer than minimum). Can be a string (query only, implies min=1) or an object with 'query', optional 'min', and 'scope' fields. Use top-level on.github-token or on.github-app for custom authentication." }, "skip-roles": { "oneOf": [ { "type": "string", "description": "Single role to skip workflow for (e.g., 'admin'). If the triggering user has this role, the workflow will be skipped." }, { "type": "array", "items": { "type": "string" }, "description": "List of roles to skip workflow for (e.g., ['admin', 'maintainer', 'write']). If the triggering user has any of these roles, the workflow will be skipped." } ], "description": "Skip workflow execution for users with specific repository roles. Useful for workflows that should only run for external contributors or specific permission levels." }, "skip-bots": { "oneOf": [ { "type": "string", "minLength": 1, "description": "Single GitHub username to skip workflow for (e.g., 'user1'). If the triggering user matches, the workflow will be skipped." }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "List of GitHub usernames to skip workflow for (e.g., ['user1', 'user2']). If the triggering user is in this list, the workflow will be skipped." } ], "description": "Skip workflow execution for specific GitHub users. Useful for preventing workflows from running for specific accounts (e.g., bots, specific team members)." }, "roles": { "description": "Repository access roles required to trigger agentic workflows. Defaults to ['admin', 'maintainer', 'write'] for security. Use 'all' to allow any authenticated user (\u26a0\ufe0f security consideration).", "oneOf": [ { "type": "string", "enum": ["all"], "description": "Allow any authenticated user to trigger the workflow (\u26a0\ufe0f disables permission checking entirely - use with caution)" }, { "type": "array", "description": "List of repository permission levels that can trigger the workflow. Permission checks are automatically applied to potentially unsafe triggers.", "items": { "type": "string", "enum": ["admin", "maintainer", "maintain", "write", "triage"], "description": "Repository permission level: 'admin' (full access), 'maintainer'/'maintain' (repository management), 'write' (push access), 'triage' (issue management)" }, "minItems": 1, "maxItems": 50 } ] }, "bots": { "type": "array", "description": "Allow list of bot identifiers that can trigger the workflow even if they don't meet the required role permissions. When the actor is in this list, the bot must be active (installed) on the repository to trigger the workflow.", "items": { "type": "string", "minLength": 1, "description": "Bot identifier/name (e.g., 'dependabot[bot]', 'renovate[bot]', 'github-actions[bot]')" } }, "manual-approval": { "type": "string", "description": "Environment name that requires manual approval before the workflow can run. Must match a valid environment configured in the repository settings." }, "reaction": { "oneOf": [ { "type": "string", "enum": ["+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes", "none"] }, { "type": "integer", "enum": [1, -1], "description": "YAML parses +1 and -1 without quotes as integers. These are converted to +1 and -1 strings respectively." } ], "default": "eyes", "description": "AI reaction to add/remove on triggering item (one of: +1, -1, laugh, confused, heart, hooray, rocket, eyes, none). Use 'none' to disable reactions. Defaults to 'eyes' if not specified.", "examples": ["eyes", "rocket", "+1", 1, -1, "none"] }, "status-comment": { "type": "boolean", "description": "Whether to post status comments (started/completed) on the triggering item. When true, adds a comment with workflow run link and updates it on completion. When false or not specified, no status comments are posted. Must be explicitly set to true to enable status comments - there is no automatic bundling with ai-reaction.", "examples": [true, false] }, "github-token": { "type": "string", "description": "Custom GitHub token for pre-activation reactions, activation status comments, and skip-if search queries. When specified, overrides the default GITHUB_TOKEN for these operations.", "examples": ["${{ secrets.MY_GITHUB_TOKEN }}"] }, "github-app": { "$ref": "#/$defs/github_app", "description": "GitHub App configuration for minting a token used in pre-activation reactions, activation status comments, and skip-if search queries. When configured, a single GitHub App installation access token is minted and shared across all these operations instead of using the default GITHUB_TOKEN. Can be defined in a shared agentic workflow and inherited by importing workflows.", "examples": [ { "app-id": "${{ vars.APP_ID }}", "private-key": "${{ secrets.APP_PRIVATE_KEY }}" } ] }, "steps": { "type": "array", "description": "Steps to inject into the pre-activation job. These steps run after all built-in checks (membership, stop-time, skip-if, etc.) and their results are exposed as pre-activation outputs. Use 'id' on steps to reference their results via needs.pre_activation.outputs._result.", "items": { "type": "object", "description": "A GitHub Actions step to inject into the pre-activation job", "properties": { "name": { "type": "string", "description": "Optional name for the step" }, "id": { "type": "string", "description": "Optional step ID. When set, the step result is exposed as needs.pre_activation.outputs._result" }, "run": { "type": "string", "description": "Shell command to run" }, "uses": { "type": "string", "description": "Action to use (e.g., 'actions/checkout@v4')" }, "with": { "type": "object", "description": "Input parameters for the action", "additionalProperties": true }, "env": { "type": "object", "description": "Environment variables for the step", "additionalProperties": { "type": "string" } }, "if": { "type": "string", "description": "Conditional expression for the step" }, "continue-on-error": { "type": "boolean", "description": "Whether to continue if the step fails" } }, "additionalProperties": true }, "examples": [ [ { "name": "Gate check", "id": "gate", "run": "echo 'Checking gate...' && exit 0" } ] ] }, "permissions": { "description": "Additional permissions for the pre-activation job. Use to declare extra scopes required by on.steps (e.g., issues: read for GitHub API calls in steps).", "oneOf": [ { "type": "object", "description": "Map of permission scope to level", "properties": { "actions": { "type": "string", "enum": ["read", "write", "none"] }, "checks": { "type": "string", "enum": ["read", "write", "none"] }, "contents": { "type": "string", "enum": ["read", "write", "none"] }, "deployments": { "type": "string", "enum": ["read", "write", "none"] }, "discussions": { "type": "string", "enum": ["read", "write", "none"] }, "issues": { "type": "string", "enum": ["read", "write", "none"] }, "packages": { "type": "string", "enum": ["read", "write", "none"] }, "pages": { "type": "string", "enum": ["read", "write", "none"] }, "pull-requests": { "type": "string", "enum": ["read", "write", "none"] }, "repository-projects": { "type": "string", "enum": ["read", "write", "none"] }, "security-events": { "type": "string", "enum": ["read", "write", "none"] }, "statuses": { "type": "string", "enum": ["read", "write", "none"] } }, "additionalProperties": false } ], "examples": [ { "issues": "read" }, { "issues": "read", "pull-requests": "read" } ] } }, "additionalProperties": false, "examples": [ { "schedule": [ { "cron": "0 0 * * *" } ], "workflow_dispatch": null }, { "schedule": [ { "cron": "30 5 * * 1-5", "timezone": "America/New_York" } ], "workflow_dispatch": null }, { "command": { "name": "mergefest", "events": ["pull_request_comment"] } }, { "workflow_run": { "workflows": ["Dev"], "types": ["completed"], "branches": ["copilot/**"] } }, { "pull_request": { "types": ["ready_for_review"] }, "workflow_dispatch": null }, { "push": { "branches": ["main"] } } ] } ] }, "permissions": { "description": "GitHub token permissions for the workflow. Controls what the GITHUB_TOKEN can access during execution. Use the principle of least privilege - only grant the minimum permissions needed.", "examples": [ "read-all", { "contents": "read", "actions": "read", "pull-requests": "read" }, { "contents": "read", "actions": "read" }, { "all": "read" } ], "oneOf": [ { "type": "string", "enum": ["read-all", "write-all"], "description": "Simple permissions string: 'read-all' (all read permissions) or 'write-all' (all write permissions)" }, { "type": "object", "description": "Detailed permissions object with granular control over specific GitHub API scopes", "additionalProperties": false, "properties": { "actions": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for GitHub Actions workflows and runs (read: view workflows, write: manage workflows, none: no access)" }, "attestations": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for artifact attestations (read: view attestations, write: create attestations, none: no access)" }, "checks": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository checks and status checks (read: view checks, write: create/update checks, none: no access)" }, "contents": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository contents (read: view files, write: modify files/branches, none: no access)" }, "deployments": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository deployments (read: view deployments, write: create/update deployments, none: no access)" }, "discussions": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository discussions (read: view discussions, write: create/update discussions, none: no access)" }, "id-token": { "type": "string", "enum": ["write", "none"], "description": "Permission level for OIDC token requests (write/none only - read is not supported). Allows workflows to request JWT tokens for cloud provider authentication." }, "issues": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository issues (read: view issues, write: create/update/close issues, none: no access)" }, "models": { "type": "string", "enum": ["read", "none"], "description": "Permission for GitHub Copilot models (read: access AI models for agentic workflows, none: no access)" }, "metadata": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission for repository metadata (read: view repository information, write: update repository metadata, none: no access)" }, "packages": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for GitHub Packages (read/write/none). Controls access to publish, modify, or delete packages." }, "pages": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for GitHub Pages (read/write/none). Controls access to deploy and manage GitHub Pages sites." }, "pull-requests": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for pull requests (read/write/none). Controls access to create, edit, review, and manage pull requests." }, "repository-projects": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for repository projects (read/write/none). Controls access to manage repository-level GitHub Projects boards." }, "organization-projects": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for organization projects (read/write/none). Controls access to manage organization-level GitHub Projects boards." }, "security-events": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for security events (read/write/none). Controls access to view and manage code scanning alerts and security findings." }, "statuses": { "type": "string", "enum": ["read", "write", "none"], "description": "Permission level for commit statuses (read/write/none). Controls access to create and update commit status checks." }, "all": { "type": "string", "enum": ["read"], "description": "Permission shorthand that applies read access to all permission scopes. Can be combined with specific write permissions to override individual scopes. 'write' is not allowed for all." } } } ] }, "run-name": { "type": "string", "description": "Custom name for workflow runs that appears in the GitHub Actions interface (supports GitHub expressions like ${{ github.event.issue.title }})", "examples": ["Deploy to ${{ github.event.inputs.environment }}", "Build #${{ github.run_number }}"] }, "jobs": { "type": "object", "description": "Groups together all the jobs that run in the workflow", "additionalProperties": { "type": "object", "description": "Job definition", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name of the job" }, "runs-on": { "oneOf": [ { "type": "string", "description": "Runner type as string" }, { "type": "array", "description": "Runner type as array", "items": { "type": "string" } }, { "type": "object", "description": "Runner type as object", "additionalProperties": false } ], "description": "Runner label or environment where the job executes. Can be a string (single runner) or array (multiple runner requirements)." }, "steps": { "type": "array", "description": "A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry.", "items": { "type": "object", "additionalProperties": false, "oneOf": [ { "required": ["uses"] }, { "required": ["run"] } ], "properties": { "id": { "type": "string", "description": "A unique identifier for the step. You can use the id to reference the step in contexts." }, "if": { "description": "You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.", "oneOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" } ] }, "name": { "type": "string", "description": "A name for your step to display on GitHub." }, "uses": { "type": "string", "description": "Selects an action to run as part of a step in your job. An action is a reusable unit of code." }, "run": { "type": "string", "description": "Runs command-line programs using the operating system's shell." }, "working-directory": { "type": "string", "description": "Working directory where to run the command." }, "shell": { "type": "string", "description": "Shell to use for running the command." }, "with": { "type": "object", "description": "A map of the input parameters defined by the action. Each input parameter is a key/value pair.", "additionalProperties": true }, "env": { "type": "object", "description": "Sets environment variables for steps to use in the virtual environment.", "additionalProperties": { "type": "string" } }, "continue-on-error": { "description": "Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.", "oneOf": [ { "type": "boolean" }, { "type": "string" } ] }, "timeout-minutes": { "description": "The maximum number of minutes to run the step before killing the process.", "oneOf": [ { "type": "number" }, { "type": "string" } ] } } } }, "if": { "type": "string", "description": "Conditional execution for the job" }, "needs": { "oneOf": [ { "type": "string", "description": "Single job dependency" }, { "type": "array", "description": "Multiple job dependencies", "items": { "type": "string" } } ], "description": "List of job IDs that must complete successfully before this job runs. Creates job dependencies for workflow orchestration." }, "env": { "type": "object", "description": "Environment variables for the job", "additionalProperties": { "type": "string" } }, "permissions": { "$ref": "#/properties/permissions", "description": "GitHub token permissions for this specific job. Overrides workflow-level permissions. Can be a string (shorthand) or object (detailed)." }, "timeout-minutes": { "type": "integer", "minimum": 1, "description": "Job timeout in minutes" }, "strategy": { "$ref": "#/$defs/job_strategy", "description": "Matrix strategy for the job. Defines multiple job configurations using matrix variables." }, "continue-on-error": { "type": "boolean", "description": "Continue workflow on job failure" }, "container": { "type": "object", "description": "Container to run the job in", "additionalProperties": false }, "services": { "type": "object", "description": "Service containers for the job", "additionalProperties": { "type": "object", "additionalProperties": false } }, "outputs": { "type": "object", "description": "Job outputs", "additionalProperties": { "type": "string" } }, "concurrency": { "$ref": "#/properties/concurrency", "description": "Concurrency control configuration for this job. Prevents parallel execution of jobs with the same concurrency group." }, "environment": { "oneOf": [ { "type": "string", "description": "The name of the GitHub Actions environment this job references. Environments can have protection rules (required reviewers, wait timers) that must be satisfied before the job runs." }, { "type": "object", "description": "Environment configuration with name and optional URL.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The name of the GitHub Actions environment." }, "url": { "type": "string", "description": "The URL to set as the environment URL in the deployment." } }, "required": ["name"] } ], "description": "The GitHub Actions environment this job references. When set, any protection rules for the environment must pass before the job runs. Use this to gate jobs on manual approval workflows." }, "uses": { "type": "string", "description": "Path to a reusable workflow file to call (e.g., ./.github/workflows/reusable-workflow.yml)" }, "with": { "type": "object", "description": "Input parameters to pass to the reusable workflow", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "secrets": { "oneOf": [ { "type": "string", "const": "inherit", "description": "Pass all secrets from the caller workflow to the reusable workflow." }, { "type": "object", "description": "Secrets to pass to the reusable workflow. Values must be GitHub Actions expressions referencing secrets (e.g., ${{ secrets.MY_SECRET }} or ${{ secrets.SECRET1 || secrets.SECRET2 }}).", "additionalProperties": { "$ref": "#/$defs/github_token" } } ] } } } }, "runs-on": { "description": "Runner type for workflow execution (GitHub Actions standard field). Supports multiple forms: simple string for single runner label (e.g., 'ubuntu-latest'), array for runner selection with fallbacks, or object for GitHub-hosted runner groups with specific labels. For agentic workflows, runner selection matters when AI workloads require specific compute resources or when using self-hosted runners with specialized capabilities. Typically configured at the job level instead. See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job", "oneOf": [ { "type": "string", "description": "Simple runner label string. Use for standard GitHub-hosted runners (e.g., 'ubuntu-latest', 'windows-latest', 'macos-latest') or self-hosted runner labels. Most common form for agentic workflows." }, { "type": "array", "description": "Array of runner labels for selection with fallbacks. GitHub Actions will use the first available runner that matches any label in the array. Useful for high-availability setups or when multiple runner types are acceptable.", "items": { "type": "string" } }, { "type": "object", "description": "Runner group configuration for GitHub-hosted runners. Use this form to target specific runner groups (e.g., larger runners with more CPU/memory) or self-hosted runner pools with specific label requirements. Agentic workflows may benefit from larger runners for complex AI processing tasks.", "additionalProperties": false, "properties": { "group": { "type": "string", "description": "Runner group name for self-hosted runners or GitHub-hosted runner groups" }, "labels": { "type": "array", "description": "List of runner labels for self-hosted runners or GitHub-hosted runner selection", "items": { "type": "string" } } } } ], "examples": [ "ubuntu-latest", ["ubuntu-latest", "self-hosted"], { "group": "larger-runners", "labels": ["ubuntu-latest-8-cores"] } ] }, "timeout-minutes": { "type": "integer", "minimum": 1, "description": "Workflow timeout in minutes (GitHub Actions standard field). Defaults to 20 minutes for agentic workflows. Has sensible defaults and can typically be omitted.", "examples": [5, 10, 30] }, "concurrency": { "description": "Concurrency control to limit concurrent workflow runs (GitHub Actions standard field). Supports two forms: simple string for basic group isolation, or object with cancel-in-progress option for advanced control. Agentic workflows enhance this with automatic per-engine concurrency policies (defaults to single job per engine across all workflows) and token-based rate limiting. Default behavior: workflows in the same group queue sequentially unless cancel-in-progress is true. See https://docs.github.com/en/actions/using-jobs/using-concurrency", "oneOf": [ { "type": "string", "description": "Simple concurrency group name to prevent multiple runs in the same group. Use expressions like '${{ github.workflow }}' for per-workflow isolation or '${{ github.ref }}' for per-branch isolation. Agentic workflows automatically generate enhanced concurrency policies using 'gh-aw-{engine-id}' as the default group to limit concurrent AI workloads across all workflows using the same engine.", "examples": ["my-workflow-group", "workflow-${{ github.ref }}"] }, { "type": "object", "description": "Concurrency configuration object with group isolation and cancellation control. Use object form when you need fine-grained control over whether to cancel in-progress runs. For agentic workflows, this is useful to prevent multiple AI agents from running simultaneously and consuming excessive resources or API quotas.", "additionalProperties": false, "properties": { "group": { "type": "string", "description": "Concurrency group name. Workflows in the same group cannot run simultaneously. Supports GitHub Actions expressions for dynamic group names based on branch, workflow, or other context." }, "cancel-in-progress": { "type": "boolean", "description": "Whether to cancel in-progress workflows in the same concurrency group when a new one starts. Default: false (queue new runs). Set to true for agentic workflows where only the latest run matters (e.g., PR analysis that becomes stale when new commits are pushed)." }, "job-discriminator": { "type": "string", "description": "Additional discriminator expression appended to compiler-generated job-level concurrency groups (agent, output jobs). Use this when multiple workflow instances are dispatched concurrently with different inputs (fan-out pattern) to prevent job-level concurrency groups from colliding. For example, '${{ inputs.finding_id }}' ensures each dispatched run gets a unique job-level group. Supports GitHub Actions expressions. This field is stripped from the compiled lock file (it is a gh-aw extension, not a GitHub Actions field).", "examples": ["${{ inputs.finding_id }}", "${{ inputs.item_id }}", "${{ github.run_id }}"] } }, "required": [], "examples": [ { "group": "dev-workflow-${{ github.ref }}", "cancel-in-progress": true }, { "job-discriminator": "${{ inputs.finding_id }}" } ] } ], "examples": [ "my-workflow-group", "workflow-${{ github.ref }}", { "group": "agentic-analysis-${{ github.workflow }}", "cancel-in-progress": false }, { "group": "pr-review-${{ github.event.pull_request.number }}", "cancel-in-progress": true } ] }, "env": { "$comment": "See environment variable precedence documentation: https://github.github.com/gh-aw/reference/environment-variables/", "description": "Environment variables for the workflow", "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "NODE_ENV": "production", "API_KEY": "${{ secrets.API_KEY }}" } ] }, { "type": "string" } ] }, "features": { "description": "Feature flags and configuration options for experimental or optional features in the workflow. Each feature can be a boolean flag or a string value. The 'action-tag' feature (string) specifies the tag or SHA to use when referencing actions/setup in compiled workflows (for testing purposes only).", "type": "object", "additionalProperties": true, "examples": [ { "action-tag": "v1.0.0" }, { "action-tag": "abc123def456", "experimental-feature": true } ] }, "infer": { "type": "boolean", "description": "DEPRECATED: Use 'disable-model-invocation' instead. Controls whether the custom agent should infer additional context from the conversation. This field is maintained for backward compatibility with existing custom agent files.", "examples": [false] }, "disable-model-invocation": { "type": "boolean", "description": "Controls whether the custom agent should disable model invocation. When set to true, the agent will not make additional model calls. This is the preferred field name for custom agent files (replaces the deprecated 'infer' field).", "examples": [true] }, "secrets": { "description": "Secret values passed to workflow execution. Secrets can be defined as simple strings (GitHub Actions expressions) or objects with 'value' and 'description' properties. Typically used to provide secrets to MCP servers or custom engines. Note: For passing secrets to reusable workflows, use the jobs..secrets field instead.", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "description": "Secret value as a GitHub Actions expression (e.g., ${{ secrets.API_KEY }})" }, { "type": "object", "description": "Secret with metadata", "required": ["value"], "properties": { "value": { "type": "string", "description": "Secret value as a GitHub Actions expression" }, "description": { "type": "string", "description": "Description of what this secret is used for" } }, "additionalProperties": false } ] }, "examples": [ { "API_TOKEN": "${{ secrets.API_TOKEN }}", "DATABASE_URL": "${{ secrets.DB_URL }}" }, { "API_TOKEN": { "value": "${{ secrets.API_TOKEN }}", "description": "API token for external service" }, "DATABASE_URL": { "value": "${{ secrets.DB_URL }}", "description": "Production database connection string" } } ] }, "environment": { "description": "Environment that the job references (for protected environments and deployments)", "oneOf": [ { "type": "string", "description": "Environment name as a string" }, { "type": "object", "description": "Environment object with name and optional URL", "properties": { "name": { "type": "string", "description": "The name of the environment configured in the repo" }, "url": { "type": "string", "description": "A deployment URL" } }, "required": ["name"], "additionalProperties": false } ] }, "container": { "description": "Container to run the job steps in", "oneOf": [ { "type": "string", "description": "Docker image name (e.g., 'node:18', 'ubuntu:latest')" }, { "type": "object", "description": "Container configuration object", "properties": { "image": { "type": "string", "description": "The Docker image to use as the container" }, "credentials": { "type": "object", "description": "Credentials for private registries", "properties": { "username": { "type": "string", "description": "Username for Docker registry authentication when pulling private container images." }, "password": { "type": "string", "description": "Password or access token for Docker registry authentication. Should use secrets syntax: ${{ secrets.DOCKER_PASSWORD }}" } }, "additionalProperties": false }, "env": { "type": "object", "description": "Environment variables for the container", "additionalProperties": { "type": "string" } }, "ports": { "type": "array", "description": "Ports to expose on the container", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "volumes": { "type": "array", "description": "Volumes for the container", "items": { "type": "string" } }, "options": { "type": "string", "description": "Additional Docker container options" } }, "required": ["image"], "additionalProperties": false } ] }, "services": { "description": "Service containers for the job", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "description": "Docker image name for the service" }, { "type": "object", "description": "Service container configuration", "properties": { "image": { "type": "string", "description": "The Docker image to use for the service" }, "credentials": { "type": "object", "description": "Credentials for private registries", "properties": { "username": { "type": "string", "description": "Username for Docker registry authentication when pulling private container images." }, "password": { "type": "string", "description": "Password or access token for Docker registry authentication. Should use secrets syntax: ${{ secrets.DOCKER_PASSWORD }}" } }, "additionalProperties": false }, "env": { "type": "object", "description": "Environment variables for the service", "additionalProperties": { "type": "string" } }, "ports": { "type": "array", "description": "Ports to expose on the service", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "volumes": { "type": "array", "description": "Volumes for the service", "items": { "type": "string" } }, "options": { "type": "string", "description": "Additional Docker container options" } }, "required": ["image"], "additionalProperties": false } ] } }, "network": { "$comment": "Strict mode requirements: When strict=true, the 'network' field must be present (not null/undefined) and cannot contain standalone wildcard '*' in allowed domains (but patterns like '*.example.com' ARE allowed). This is validated in Go code (pkg/workflow/strict_mode_validation.go) via validateStrictNetwork().", "description": "Network access control for AI engines using ecosystem identifiers and domain allowlists. Supports wildcard patterns like '*.example.com' to match any subdomain. Controls web fetch and search capabilities. IMPORTANT: For workflows that build/install/test code, always include the language ecosystem identifier alongside 'defaults' \u2014 'defaults' alone only covers basic infrastructure, not package registries. Key ecosystem identifiers by runtime: 'dotnet' (.NET/NuGet), 'python' (pip/PyPI), 'node' (npm/yarn), 'go' (go modules), 'java' (Maven/Gradle), 'ruby' (Bundler), 'rust' (Cargo), 'swift' (Swift PM). Example: a .NET project needs network: { allowed: [defaults, dotnet] }.", "examples": [ "defaults", { "allowed": ["defaults", "github"] }, { "allowed": ["defaults", "python", "node", "*.example.com"] }, { "allowed": ["api.openai.com", "*.github.com"], "firewall": { "version": "v1.0.0", "log-level": "debug" } } ], "oneOf": [ { "type": "string", "enum": ["defaults"], "description": "Use default network permissions (basic infrastructure: certificates, JSON schema, Ubuntu, etc.)" }, { "type": "object", "description": "Custom network access configuration with ecosystem identifiers and specific domains", "properties": { "allowed": { "type": "array", "description": "List of allowed domains or ecosystem identifiers (e.g., 'defaults', 'python', 'node', '*.example.com'). Wildcard patterns match any subdomain AND the base domain.", "items": { "type": "string", "description": "Domain name or ecosystem identifier. Supports wildcards like '*.example.com' (matches sub.example.com, deep.nested.example.com, and example.com itself). Ecosystem identifiers by runtime: 'dotnet' (.NET/NuGet), 'python' (pip/PyPI), 'node' (npm/yarn), 'go' (go modules), 'java' (Maven/Gradle), 'ruby' (RubyGems), 'rust' (Cargo), 'swift' (Swift PM), 'php' (Composer), 'dart' (pub.dev), 'haskell' (Hackage), 'perl' (CPAN), 'containers' (Docker/GHCR), 'github' (GitHub domains), 'terraform' (HashiCorp), 'linux-distros' (apt/yum), 'playwright' (browser testing), 'defaults' (basic infrastructure)." }, "$comment": "Empty array is valid and means deny all network access. Omit the field entirely or use network: defaults to use default network permissions. Wildcard patterns like '*.example.com' are allowed; only standalone '*' is blocked in strict mode." }, "blocked": { "type": "array", "description": "List of blocked domains or ecosystem identifiers (e.g., 'python', 'node', 'tracker.example.com'). Blocked domains take precedence over allowed domains.", "items": { "type": "string", "description": "Domain name or ecosystem identifier to block. Supports wildcards like '*.example.com' (matches sub.example.com, deep.nested.example.com, and example.com itself) and ecosystem names like 'python', 'node'." }, "$comment": "Blocked domains are subtracted from the allowed list. Useful for blocking specific domains or ecosystems within broader allowed categories." }, "firewall": { "description": "AWF (Agent Workflow Firewall) configuration for network egress control. Supported for copilot, claude, codex, and gemini engines.", "deprecated": true, "x-deprecation-message": "The firewall is now always enabled. Use 'sandbox.agent' to configure the sandbox type.", "oneOf": [ { "type": "null", "description": "Enable AWF with default settings (equivalent to empty object)" }, { "type": "boolean", "description": "Enable (true) or explicitly disable (false) AWF firewall" }, { "type": "string", "enum": ["disable"], "description": "Disable AWF firewall (triggers warning if allowed != *, error in strict mode if allowed is not * or engine does not support firewall)" }, { "type": "object", "description": "Custom AWF configuration with version and arguments", "properties": { "args": { "type": "array", "description": "Optional additional arguments to pass to AWF wrapper", "items": { "type": "string" } }, "version": { "type": ["string", "number"], "description": "AWF version to use (empty = latest release). Can be a string (e.g., 'v1.0.0', 'latest') or number (e.g., 20, 3.11). Numeric values are automatically converted to strings at runtime.", "examples": ["v1.0.0", "latest", 20, 3.11] }, "log-level": { "type": "string", "description": "AWF log level (default: info). Valid values: debug, info, warn, error", "enum": ["debug", "info", "warn", "error"] }, "ssl-bump": { "type": "boolean", "description": "Enable SSL Bump for HTTPS content inspection. When enabled, AWF can filter HTTPS traffic by URL patterns instead of just domain names. This feature is specific to AWF. Default: false", "default": false }, "allow-urls": { "type": "array", "description": "URL patterns to allow for HTTPS traffic (requires ssl-bump: true). Supports wildcards for flexible path matching. Must include https:// scheme. This feature is specific to AWF.", "items": { "type": "string", "pattern": "^https://.*", "description": "HTTPS URL pattern with optional wildcards (e.g., 'https://github.com/githubnext/*')" }, "examples": [["https://github.com/githubnext/*", "https://api.github.com/repos/*"]] }, "cleanup-script": { "type": "string", "description": "Path to cleanup script run after AWF shuts down (default: ./scripts/ci/cleanup.sh)" } }, "additionalProperties": false } ] } }, "additionalProperties": false } ] }, "sandbox": { "description": "Sandbox configuration for AI engines. Controls agent sandbox (AWF) and MCP gateway. The MCP gateway is always enabled and cannot be disabled.", "oneOf": [ { "type": "string", "enum": ["default", "awf"], "description": "String format for sandbox type: 'default' for no sandbox, 'awf' for Agent Workflow Firewall. Note: Legacy 'srt' and 'sandbox-runtime' values are automatically migrated to 'awf'" }, { "type": "object", "description": "Object format for full sandbox configuration with agent and mcp options", "properties": { "type": { "type": "string", "enum": ["default", "awf"], "description": "Legacy sandbox type field (use agent instead). Note: Legacy 'srt' and 'sandbox-runtime' values are automatically migrated to 'awf'" }, "agent": { "description": "Agent sandbox type: 'awf' uses AWF (Agent Workflow Firewall), or false to disable agent sandbox. Defaults to 'awf' if not specified. Note: Disabling the agent sandbox (false) removes firewall protection but keeps the MCP gateway enabled.", "default": "awf", "oneOf": [ { "type": "boolean", "const": false, "description": "Set to false to disable the agent sandbox (firewall). Warning: This removes firewall protection but keeps the MCP gateway enabled. Not allowed in strict mode." }, { "type": "string", "enum": ["awf"], "description": "Sandbox type: 'awf' for Agent Workflow Firewall" }, { "type": "object", "description": "Custom sandbox runtime configuration", "properties": { "id": { "type": "string", "enum": ["awf"], "description": "Agent identifier (replaces 'type' field in new format): 'awf' for Agent Workflow Firewall" }, "type": { "type": "string", "enum": ["awf"], "description": "Legacy: Sandbox type to use (use 'id' instead)" }, "command": { "type": "string", "description": "Custom command to replace the default AWF installation. For AWF: 'docker run my-custom-awf-image'" }, "args": { "type": "array", "description": "Additional arguments to append to the command (applies to AWF, for standard and custom commands)", "items": { "type": "string" } }, "env": { "type": "object", "description": "Environment variables to set on the execution step (applies to AWF)", "additionalProperties": { "type": "string" } }, "mounts": { "type": "array", "description": "Container mounts to add when using AWF. Each mount is specified using Docker mount syntax: 'source:destination:mode' where mode can be 'ro' (read-only) or 'rw' (read-write). Example: '/host/path:/container/path:ro'", "items": { "type": "string", "pattern": "^[^:]+:[^:]+:(ro|rw)$", "description": "Mount specification in format 'source:destination:mode'" }, "examples": [["/host/data:/data:ro", "/usr/local/bin/custom-tool:/usr/local/bin/custom-tool:ro"]] }, "memory": { "type": "string", "description": "Memory limit for the AWF container (e.g., '4g', '8g'). Passed as --memory-limit to AWF. If not specified, AWF's default memory limit is used.", "pattern": "^[0-9]+(b|k|m|g|kb|mb|gb|B|K|M|G|KB|MB|GB)$", "examples": ["4g", "8g", "512m"] }, "config": { "type": "object", "description": "Custom sandbox runtime configuration. Note: Network configuration is controlled by the top-level 'network' field, not here.", "properties": { "filesystem": { "type": "object", "properties": { "denyRead": { "type": "array", "description": "List of paths to deny read access", "items": { "type": "string" } }, "allowWrite": { "type": "array", "description": "List of paths to allow write access", "items": { "type": "string" } }, "denyWrite": { "type": "array", "description": "List of paths to deny write access", "items": { "type": "string" } } }, "additionalProperties": false, "description": "Filesystem access control configuration for the agent within the sandbox. Controls read/write permissions and path restrictions." }, "ignoreViolations": { "type": "object", "description": "Map of command patterns to paths that should ignore violations", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "enableWeakerNestedSandbox": { "type": "boolean", "description": "Enable weaker nested sandbox mode (recommended: true for Docker access)" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "config": { "type": "object", "description": "Legacy custom Sandbox Runtime configuration (use agent.config instead). Note: Network configuration is controlled by the top-level 'network' field, not here.", "properties": { "filesystem": { "type": "object", "properties": { "denyRead": { "type": "array", "items": { "type": "string" }, "description": "Array of path patterns that deny read access in the sandboxed environment. Takes precedence over other read permissions." }, "allowWrite": { "type": "array", "items": { "type": "string" }, "description": "Array of path patterns that allow write access in the sandboxed environment. Paths outside these patterns are read-only." }, "denyWrite": { "type": "array", "items": { "type": "string" }, "description": "Array of path patterns that deny write access in the sandboxed environment. Takes precedence over other write permissions." } }, "additionalProperties": false, "description": "Filesystem access control configuration for sandboxed workflows. Controls read/write permissions and path restrictions for file operations." }, "ignoreViolations": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "When true, log sandbox violations without blocking execution. Useful for debugging and gradual enforcement of sandbox policies." }, "enableWeakerNestedSandbox": { "type": "boolean", "description": "When true, allows nested sandbox processes to run with relaxed restrictions. Required for certain containerized tools that spawn subprocesses." } }, "additionalProperties": false }, "mcp": { "description": "MCP Gateway configuration for routing MCP server calls through a unified HTTP gateway. Requires the 'mcp-gateway' feature flag to be enabled. Per MCP Gateway Specification v1.0.0: Only container-based execution is supported.", "type": "object", "properties": { "container": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$", "description": "Container image for the MCP gateway executable (required)" }, "version": { "type": ["string", "number"], "description": "Optional version/tag for the container image (e.g., 'latest', 'v1.0.0')", "examples": ["latest", "v1.0.0"] }, "entrypoint": { "type": "string", "description": "Optional custom entrypoint for the MCP gateway container. Overrides the container's default entrypoint.", "examples": ["/bin/bash", "/custom/start.sh", "/usr/bin/env"] }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments for docker run" }, "entrypointArgs": { "type": "array", "items": { "type": "string" }, "description": "Arguments to add after the container image (container entrypoint arguments)" }, "mounts": { "type": "array", "description": "Volume mounts for the MCP gateway container. Each mount is specified using Docker mount syntax: 'source:destination:mode' where mode can be 'ro' (read-only) or 'rw' (read-write). Example: '/host/data:/container/data:ro'", "items": { "type": "string", "pattern": "^[^:]+:[^:]+:(ro|rw)$", "description": "Mount specification in format 'source:destination:mode'" }, "examples": [["/host/data:/container/data:ro", "/host/config:/container/config:rw"]] }, "env": { "type": "object", "patternProperties": { "^[A-Z_][A-Z0-9_]*$": { "type": "string" } }, "additionalProperties": false, "description": "Environment variables for MCP gateway" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "default": 8080, "description": "Port number for the MCP gateway HTTP server (default: 8080)" }, "api-key": { "type": "string", "description": "API key for authenticating with the MCP gateway (supports ${{ secrets.* }} syntax)" }, "domain": { "type": "string", "enum": ["localhost", "host.docker.internal"], "description": "Gateway domain for URL generation (default: 'host.docker.internal' when agent is enabled, 'localhost' when disabled)" } }, "required": ["container"], "additionalProperties": false } }, "additionalProperties": false } ], "examples": [ "default", { "agent": "awf" }, { "mcp": { "container": "ghcr.io/githubnext/mcp-gateway", "port": 8080 } }, { "agent": "awf", "mcp": { "container": "ghcr.io/githubnext/mcp-gateway", "port": 8080, "api-key": "${{ secrets.MCP_GATEWAY_API_KEY }}" } } ] }, "plugins": { "description": "\u26a0\ufe0f EXPERIMENTAL: Plugin configuration for installing plugins before workflow execution. Supports array format (list of repos/plugin configs) and object format (repos + custom token). Note: Plugin support is experimental and may change in future releases.", "examples": [ ["github/copilot-plugin", "acme/custom-tools"], [ "github/simple-plugin", { "id": "github/mcp-plugin", "mcp": { "env": { "API_KEY": "${{ secrets.API_KEY }}" } } } ], { "repos": ["github/copilot-plugin", "acme/custom-tools"], "github-token": "${{ secrets.CUSTOM_PLUGIN_TOKEN }}" } ], "oneOf": [ { "type": "array", "description": "List of plugins to install. Each item can be either a repository slug string (e.g., 'org/repo') or an object with id and optional MCP configuration.", "items": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$", "description": "Plugin repository slug in the format 'org/repo' (e.g., 'github/example-plugin')" }, { "type": "object", "description": "Plugin configuration with ID and optional MCP settings for environment variables", "required": ["id"], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$", "description": "Plugin repository slug in the format 'org/repo' (e.g., 'github/example-plugin')" }, "mcp": { "type": "object", "description": "MCP server configuration for this plugin. When defined, the compiler scans the plugin's MCP JSON and mounts it in the gateway with the specified environment variables.", "properties": { "env": { "type": "object", "description": "Environment variables to pass when instantiating the MCP server. These variables are made available to the MCP server at runtime and can reference secrets using ${{ secrets.SECRET_NAME }} syntax.", "additionalProperties": { "type": "string" }, "examples": [ { "API_KEY": "${{ secrets.API_KEY }}", "API_URL": "https://api.example.com" } ] } }, "additionalProperties": false } }, "additionalProperties": false } ] } }, { "type": "object", "description": "Plugin configuration with custom GitHub token. Repos can be either strings or objects with MCP configuration.", "required": ["repos"], "properties": { "repos": { "type": "array", "description": "List of plugins to install. Each item can be either a repository slug string or an object with id and optional MCP configuration.", "items": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$", "description": "Plugin repository slug in the format 'org/repo' (e.g., 'github/example-plugin')" }, { "type": "object", "description": "Plugin configuration with ID and optional MCP settings", "required": ["id"], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$", "description": "Plugin repository slug in the format 'org/repo' (e.g., 'github/example-plugin')" }, "mcp": { "type": "object", "description": "MCP server configuration for this plugin", "properties": { "env": { "type": "object", "description": "Environment variables for the MCP server", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } ] } }, "github-token": { "type": "string", "description": "Custom GitHub token expression to use for plugin installation. Overrides the default cascading token resolution (GH_AW_PLUGINS_TOKEN -> GH_AW_GITHUB_TOKEN -> GITHUB_TOKEN).", "examples": ["${{ secrets.CUSTOM_PLUGIN_TOKEN }}"] } }, "additionalProperties": false } ] }, "if": { "type": "string", "description": "Conditional execution expression", "examples": ["${{ github.event.workflow_run.event == 'workflow_dispatch' }}", "${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}"] }, "steps": { "description": "Custom workflow steps", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "examples": [ [ { "prompt": "Analyze the issue and create a plan" } ], [ { "uses": "actions/checkout@v4" }, { "prompt": "Review the code and suggest improvements" } ], [ { "name": "Download logs from last 24 hours", "env": { "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}" }, "run": "./gh-aw logs --start-date -1d -o /tmp/gh-aw/aw-mcp/logs" } ] ] } ] }, "post-steps": { "description": "Custom workflow steps to run after AI execution", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "examples": [ [ { "name": "Verify Post-Steps Execution", "run": "echo \"\u2705 Post-steps are executing correctly\"\necho \"This step runs after the AI agent completes\"\n" }, { "name": "Upload Test Results", "if": "always()", "uses": "actions/upload-artifact@v4", "with": { "name": "post-steps-test-results", "path": "/tmp/gh-aw/", "retention-days": 1, "if-no-files-found": "ignore" } } ] ] } ] }, "engine": { "description": "AI engine configuration that specifies which AI processor interprets and executes the markdown content of the workflow. Defaults to 'copilot'.", "default": "copilot", "examples": [ "copilot", "claude", "codex", { "id": "copilot", "version": "beta" }, { "id": "claude", "model": "claude-3-5-sonnet-20241022", "max-turns": 15 } ], "$ref": "#/$defs/engine_config" }, "mcp-servers": { "type": "object", "description": "MCP server definitions", "examples": [ { "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } }, { "custom-server": { "type": "http", "url": "https://api.example.com/mcp" } } ], "patternProperties": { "^[a-zA-Z0-9_-]+$": { "oneOf": [ { "$ref": "#/$defs/stdio_mcp_tool" }, { "$ref": "#/$defs/http_mcp_tool" } ] } }, "additionalProperties": false }, "tools": { "type": "object", "description": "Tools and MCP (Model Context Protocol) servers available to the AI engine for GitHub API access, browser automation, file editing, and more", "examples": [ { "playwright": { "version": "v1.41.0" } }, { "github": { "mode": "remote" } }, { "github": { "mode": "local", "version": "latest" } }, { "bash": null } ], "properties": { "github": { "description": "GitHub API tools for repository operations (issues, pull requests, content management)", "oneOf": [ { "type": "null", "description": "Empty GitHub tool configuration (enables all read-only GitHub API functions)" }, { "type": "boolean", "description": "Boolean to explicitly enable (true) or disable (false) the GitHub MCP server. When set to false, the GitHub MCP server is not mounted." }, { "type": "string", "description": "Simple GitHub tool configuration (enables all GitHub API functions)" }, { "type": "object", "description": "GitHub tools object configuration with restricted function access", "properties": { "allowed": { "type": "array", "description": "List of allowed GitHub API functions (e.g., 'create_issue', 'update_issue', 'add_comment')", "items": { "type": "string" } }, "mode": { "type": "string", "enum": ["local", "remote"], "description": "MCP server mode: 'local' (Docker-based, default) or 'remote' (hosted at api.githubcopilot.com)" }, "version": { "type": ["string", "number"], "description": "Optional version specification for the GitHub MCP server (used with 'local' type). Can be a string (e.g., 'v1.0.0', 'latest') or number (e.g., 20, 3.11). Numeric values are automatically converted to strings at runtime.", "examples": ["v1.0.0", "latest", 20, 3.11] }, "args": { "type": "array", "description": "Optional additional arguments to append to the generated MCP server command (used with 'local' type)", "items": { "type": "string" } }, "read-only": { "type": "boolean", "description": "Enable read-only mode to restrict GitHub MCP server to read-only operations only" }, "lockdown": { "type": "boolean", "description": "Enable lockdown mode to limit content surfaced from public repositories (only items authored by users with push access). Default: false", "default": false }, "github-token": { "$ref": "#/$defs/github_token", "description": "Optional custom GitHub token (e.g., '${{ secrets.CUSTOM_PAT }}'). For 'remote' type, defaults to GH_AW_GITHUB_TOKEN if not specified." }, "toolsets": { "type": "array", "description": "Array of GitHub MCP server toolset names to enable specific groups of GitHub API functionalities", "items": { "type": "string", "description": "Toolset name", "enum": [ "all", "default", "action-friendly", "context", "repos", "issues", "pull_requests", "actions", "code_security", "dependabot", "discussions", "experiments", "gists", "labels", "notifications", "orgs", "projects", "search", "secret_protection", "security_advisories", "stargazers", "users" ] }, "minItems": 1, "$comment": "At least one toolset is required when toolsets array is specified. Use null or omit the field to use all toolsets.", "maxItems": 20 }, "mounts": { "type": "array", "description": "Volume mounts for the containerized GitHub MCP server (format: 'host:container:mode' where mode is 'ro' for read-only or 'rw' for read-write). Applies to local mode only. Example: '/data:/data:ro'", "items": { "type": "string", "pattern": "^[^:]+:[^:]+(:(ro|rw))?$", "description": "Mount specification in format 'host:container:mode'" }, "examples": [["/data:/data:ro", "/tmp:/tmp:rw"], ["/opt:/opt:ro"]] }, "repos": { "description": "Guard policy: repository access configuration. Restricts which repositories the agent can access. Use 'all' to allow all repos, 'public' for public repositories only, or an array of repository patterns (e.g., 'owner/repo', 'owner/*', 'owner/prefix*').", "oneOf": [ { "type": "string", "enum": ["all", "public"], "description": "Allow access to all repositories ('all') or only public repositories ('public')" }, { "type": "array", "description": "Allow access to specific repositories using patterns (e.g., 'owner/repo', 'owner/*', 'owner/prefix*')", "items": { "type": "string", "description": "Repository pattern in the format 'owner/repo', 'owner/*' (all repos under owner), or 'owner/prefix*' (repos with name prefix)" }, "minItems": 1 } ] }, "min-integrity": { "type": "string", "description": "Guard policy: minimum required integrity level for repository access. Restricts the agent to users with at least the specified permission level.", "enum": ["none", "unapproved", "approved", "merged"] }, "github-app": { "$ref": "#/$defs/github_app", "description": "GitHub App configuration for token minting. When configured, a GitHub App installation access token is minted at workflow start and used instead of the default token. This token overrides any custom github-token setting and provides fine-grained permissions matching the agent job requirements.", "examples": [ { "app-id": "${{ vars.APP_ID }}", "private-key": "${{ secrets.APP_PRIVATE_KEY }}" }, { "app-id": "${{ vars.APP_ID }}", "private-key": "${{ secrets.APP_PRIVATE_KEY }}", "repositories": ["repo1", "repo2"] } ] } }, "additionalProperties": false, "examples": [ { "toolsets": ["pull_requests", "actions", "repos"] }, { "allowed": ["search_pull_requests", "pull_request_read", "list_pull_requests", "get_file_contents", "list_commits", "get_commit"] }, { "read-only": true }, { "toolsets": ["pull_requests", "repos"] } ] } ], "examples": [ null, { "toolsets": ["pull_requests", "actions", "repos"] }, { "allowed": ["search_pull_requests", "pull_request_read", "get_file_contents"] }, { "read-only": true, "toolsets": ["repos", "issues"] }, false ] }, "bash": { "description": "Bash shell command execution tool. Supports wildcards: '*' (all commands), 'command *' (command with any args, e.g., 'date *', 'echo *'). Default safe commands: echo, ls, pwd, cat, head, tail, grep, wc, sort, uniq, date.", "oneOf": [ { "type": "null", "description": "Enable bash tool with all shell commands allowed (security consideration: use restricted list in production)" }, { "type": "boolean", "description": "Enable bash tool - true allows all commands (equivalent to ['*']), false disables the tool" }, { "type": "array", "description": "List of allowed commands and patterns. Wildcards: '*' allows all commands, 'command *' allows command with any args (e.g., 'date *', 'echo *').", "items": { "type": "string", "description": "Command or pattern: 'echo' (exact match), 'echo *' (command with any args)" } } ], "examples": [ true, ["git fetch", "git checkout", "git status", "git diff", "git log", "make recompile", "make fmt", "make lint", "make test-unit", "cat", "echo", "ls"], ["echo", "ls", "cat"], ["gh pr list *", "gh search prs *", "jq *"], ["date *", "echo *", "cat", "ls"] ] }, "web-fetch": { "description": "Web content fetching tool for downloading web pages and API responses (subject to network permissions)", "oneOf": [ { "type": "null", "description": "Enable web fetch tool with default configuration" }, { "type": "object", "description": "Web fetch tool configuration object", "additionalProperties": false } ] }, "web-search": { "description": "Web search tool for performing internet searches and retrieving search results (subject to network permissions)", "oneOf": [ { "type": "null", "description": "Enable web search tool with default configuration" }, { "type": "object", "description": "Web search tool configuration object", "additionalProperties": false } ] }, "grep": { "description": "DEPRECATED: grep is always available as part of default bash tools. This field is no longer needed and will be ignored.", "deprecated": true, "x-deprecation-message": "grep is always available as part of default bash tools (echo, ls, pwd, cat, head, tail, grep, wc, sort, uniq, date, yq). Remove this field and use bash tool instead.", "oneOf": [ { "type": "null", "description": "Deprecated grep tool configuration" }, { "type": "boolean", "description": "Deprecated grep tool configuration" }, { "type": "object", "description": "Deprecated grep tool configuration object", "additionalProperties": true } ] }, "edit": { "description": "File editing tool for reading, creating, and modifying files in the repository", "oneOf": [ { "type": "null", "description": "Enable edit tool" }, { "type": "object", "description": "Edit tool configuration object", "additionalProperties": false } ] }, "playwright": { "description": "Playwright browser automation tool for web scraping, testing, and UI interactions in containerized browsers", "oneOf": [ { "type": "null", "description": "Enable Playwright tool with default settings" }, { "type": "object", "description": "Playwright tool configuration with custom version and arguments", "properties": { "version": { "type": ["string", "number"], "description": "Optional Playwright container version (e.g., 'v1.41.0', 1.41, 20). Numeric values are automatically converted to strings at runtime.", "examples": ["v1.41.0", 1.41, 20] }, "args": { "type": "array", "description": "Optional additional arguments to append to the generated MCP server command", "items": { "type": "string" } } }, "additionalProperties": false } ] }, "agentic-workflows": { "description": "GitHub Agentic Workflows MCP server for workflow introspection and analysis. Provides tools for checking status, compiling workflows, downloading logs, and auditing runs.", "oneOf": [ { "type": "boolean", "description": "Enable agentic-workflows tool with default settings" }, { "type": "null", "description": "Enable agentic-workflows tool with default settings (same as true)" } ], "examples": [true, null] }, "cache-memory": { "description": "Cache memory MCP configuration for persistent memory storage", "oneOf": [ { "type": "boolean", "description": "Enable cache-memory with default settings" }, { "type": "null", "description": "Enable cache-memory with default settings (same as true)" }, { "type": "object", "description": "Cache-memory configuration object", "properties": { "key": { "type": "string", "description": "Custom cache key for memory MCP data (restore keys are auto-generated by splitting on '-')" }, "description": { "type": "string", "description": "Optional description for the cache that will be shown in the agent prompt" }, "retention-days": { "type": "integer", "minimum": 1, "maximum": 90, "description": "Number of days to retain uploaded artifacts (1-90 days, default: repository setting)" }, "restore-only": { "type": "boolean", "description": "If true, only restore the cache without saving it back. Uses actions/cache/restore instead of actions/cache. No artifact upload step will be generated." }, "scope": { "type": "string", "enum": ["workflow", "repo"], "default": "workflow", "description": "Cache restore key scope: 'workflow' (default, only restores from same workflow) or 'repo' (restores from any workflow in the repository). Use 'repo' with caution as it allows cross-workflow cache sharing." }, "allowed-extensions": { "type": "array", "items": { "type": "string" }, "description": "List of allowed file extensions (e.g., [\".json\", \".txt\"]). Default: [\".json\", \".jsonl\", \".txt\", \".md\", \".csv\"]" } }, "additionalProperties": false, "examples": [ { "key": "memory-audit-${{ github.workflow }}" }, { "key": "memory-copilot-analysis", "retention-days": 30 } ] }, { "type": "array", "description": "Array of cache-memory configurations for multiple caches", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cache identifier for this cache entry" }, "key": { "type": "string", "description": "Cache key for this memory cache (supports GitHub Actions expressions like ${{ github.workflow }}, ${{ github.run_id }}). Restore keys are auto-generated by splitting on '-'." }, "description": { "type": "string", "description": "Optional description for this cache that will be shown in the agent prompt" }, "retention-days": { "type": "integer", "minimum": 1, "maximum": 90, "description": "Number of days to retain uploaded artifacts (1-90 days, default: repository setting)" }, "restore-only": { "type": "boolean", "description": "If true, only restore the cache without saving it back. Uses actions/cache/restore instead of actions/cache. No artifact upload step will be generated." }, "scope": { "type": "string", "enum": ["workflow", "repo"], "default": "workflow", "description": "Cache restore key scope: 'workflow' (default, only restores from same workflow) or 'repo' (restores from any workflow in the repository). Use 'repo' with caution as it allows cross-workflow cache sharing." }, "allowed-extensions": { "type": "array", "items": { "type": "string" }, "description": "List of allowed file extensions (e.g., [\".json\", \".txt\"]). Default: [\".json\", \".jsonl\", \".txt\", \".md\", \".csv\"]" } }, "required": ["id", "key"], "additionalProperties": false }, "minItems": 1, "examples": [ [ { "id": "default", "key": "memory-default" }, { "id": "session", "key": "memory-session" } ] ], "maxItems": 10 } ], "examples": [ true, null, { "key": "memory-audit-workflow" }, [ { "id": "default", "key": "memory-default" }, { "id": "logs", "key": "memory-logs" } ] ] }, "timeout": { "type": "integer", "minimum": 1, "description": "Timeout in seconds for tool/MCP server operations. Applies to all tools and MCP servers if supported by the engine. Default varies by engine (Claude: 60s, Codex: 120s).", "examples": [60, 120, 300] }, "startup-timeout": { "type": "integer", "minimum": 1, "description": "Timeout in seconds for MCP server startup. Applies to MCP server initialization if supported by the engine. Default: 120 seconds." }, "serena": { "description": "Serena MCP server for AI-powered code intelligence with language service integration", "oneOf": [ { "type": "null", "description": "Enable Serena with default settings" }, { "type": "array", "description": "Short syntax: array of language identifiers to enable (e.g., [\"go\", \"typescript\"]). Note: rust does not generate a runtime setup step.", "items": { "type": "string", "enum": [ "go", "typescript", "javascript", "python", "java", "rust", "csharp", "cpp", "c", "ruby", "php", "bash", "swift", "kotlin", "scala", "haskell", "elixir", "erlang", "clojure", "lua", "perl", "r", "dart", "julia", "fortran", "nix", "rego", "terraform", "yaml", "markdown", "zig", "elm" ] } }, { "type": "object", "description": "Serena configuration with custom version and language-specific settings", "properties": { "version": { "type": ["string", "number"], "description": "Optional Serena MCP version. Numeric values are automatically converted to strings at runtime.", "examples": ["latest", "0.1.0", 1.0] }, "mode": { "type": "string", "description": "Serena execution mode (only 'docker' is supported, runs in container)", "enum": ["docker"], "default": "docker" }, "args": { "type": "array", "description": "Optional additional arguments to append to the generated MCP server command", "items": { "type": "string" } }, "languages": { "type": "object", "description": "Language-specific configuration for Serena language services", "properties": { "go": { "oneOf": [ { "type": "null", "description": "Enable Go language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": "Go version (e.g., \"1.21\", 1.21)" }, "go-mod-file": { "type": "string", "description": "Path to go.mod file for Go version detection (e.g., \"go.mod\", \"backend/go.mod\")" }, "gopls-version": { "type": "string", "description": "Version of gopls to install (e.g., \"latest\", \"v0.14.2\")" } }, "additionalProperties": false } ], "description": "Configuration for Go language support in Serena code analysis. Enables Go-specific parsing, linting, and security checks." }, "typescript": { "oneOf": [ { "type": "null", "description": "Enable TypeScript language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": "Node.js version for TypeScript (e.g., \"22\", 22)" } }, "additionalProperties": false } ], "description": "Configuration for TypeScript language support in Serena code analysis. Enables TypeScript-specific parsing, linting, and type checking." }, "python": { "oneOf": [ { "type": "null", "description": "Enable Python language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": "Python version (e.g., \"3.12\", 3.12)" } }, "additionalProperties": false } ], "description": "Configuration for Python language support in Serena code analysis. Enables Python-specific parsing, linting, and security checks." }, "java": { "oneOf": [ { "type": "null", "description": "Enable Java language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": "Java version (e.g., \"21\", 21)" } }, "additionalProperties": false } ], "description": "Configuration for Java language support in Serena code analysis. Enables Java-specific parsing, linting, and security checks." }, "rust": { "oneOf": [ { "type": "null", "description": "Enable Rust language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": "Rust version (e.g., \"stable\", \"1.75\")" } }, "additionalProperties": false } ], "description": "Configuration for Rust language support in Serena code analysis. Enables Rust-specific parsing, linting, and security checks. Note: rust does not generate a runtime setup step in GitHub Actions." }, "csharp": { "oneOf": [ { "type": "null", "description": "Enable C# language service with default version" }, { "type": "object", "properties": { "version": { "type": ["string", "number"], "description": ".NET version for C# (e.g., \"8.0\", 8.0)" } }, "additionalProperties": false } ], "description": "Configuration for C# language support in Serena code analysis. Enables C#-specific parsing, linting, and security checks." } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "repo-memory": { "description": "Repo memory configuration for git-based persistent storage", "oneOf": [ { "type": "boolean", "description": "Enable repo-memory with default settings" }, { "type": "null", "description": "Enable repo-memory with default settings (same as true)" }, { "type": "object", "description": "Repo-memory configuration object", "properties": { "branch-prefix": { "type": "string", "minLength": 4, "maxLength": 32, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Branch prefix for memory storage (default: 'memory'). Must be 4-32 characters, alphanumeric with hyphens/underscores, and cannot be 'copilot'. Branch will be named {branch-prefix}/{id}" }, "target-repo": { "type": "string", "description": "Target repository for memory storage (default: current repository). Format: owner/repo" }, "branch-name": { "type": "string", "description": "Git branch name for memory storage (default: {branch-prefix}/default or memory/default if branch-prefix not set)" }, "file-glob": { "oneOf": [ { "type": "string", "description": "Single file glob pattern for allowed files" }, { "type": "array", "description": "Array of file glob patterns for allowed files", "items": { "type": "string" } } ], "description": "Glob patterns for files to include in repository memory. Supports wildcards (e.g., '**/*.md', 'docs/**/*.json') to filter cached files." }, "max-file-size": { "type": "integer", "minimum": 1, "maximum": 104857600, "description": "Maximum size per file in bytes (default: 10240 = 10KB)" }, "max-file-count": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum file count per commit (default: 100)" }, "max-patch-size": { "type": "integer", "minimum": 1, "maximum": 102400, "description": "Maximum total patch size in bytes (default: 10240 = 10KB, max: 102400 = 100KB). The total size of the git diff must not exceed this value." }, "description": { "type": "string", "description": "Optional description for the memory that will be shown in the agent prompt" }, "create-orphan": { "type": "boolean", "description": "Create orphaned branch if it doesn't exist (default: true)" }, "wiki": { "type": "boolean", "description": "Use the GitHub Wiki git repository instead of the regular repository. When enabled, files are stored in and read from the wiki, and the agent will be instructed to follow GitHub Wiki markdown syntax (default: false)" }, "allowed-extensions": { "type": "array", "items": { "type": "string" }, "description": "List of allowed file extensions (e.g., [\".json\", \".txt\"]). Default: [\".json\", \".jsonl\", \".txt\", \".md\", \".csv\"]" } }, "additionalProperties": false, "examples": [ { "branch-name": "memory/session-state" }, { "target-repo": "myorg/memory-repo", "branch-name": "memory/agent-notes", "max-file-size": 524288 } ] }, { "type": "array", "description": "Array of repo-memory configurations for multiple memory locations", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory identifier (required for array notation, default: 'default')" }, "branch-prefix": { "type": "string", "minLength": 4, "maxLength": 32, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Branch prefix for memory storage (default: 'memory'). Must be 4-32 characters, alphanumeric with hyphens/underscores, and cannot be 'copilot'. Applied to all entries in the array. Branch will be named {branch-prefix}/{id}" }, "target-repo": { "type": "string", "description": "Target repository for memory storage (default: current repository). Format: owner/repo" }, "branch-name": { "type": "string", "description": "Git branch name for memory storage (default: {branch-prefix}/{id} or memory/{id} if branch-prefix not set)" }, "file-glob": { "oneOf": [ { "type": "string", "description": "Single file glob pattern for allowed files" }, { "type": "array", "description": "Array of file glob patterns for allowed files", "items": { "type": "string" } } ], "description": "Glob patterns for files to include in repository memory. Supports wildcards (e.g., '**/*.md', 'docs/**/*.json') to filter cached files." }, "max-file-size": { "type": "integer", "minimum": 1, "maximum": 104857600, "description": "Maximum size per file in bytes (default: 10240 = 10KB)" }, "max-file-count": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum file count per commit (default: 100)" }, "max-patch-size": { "type": "integer", "minimum": 1, "maximum": 102400, "description": "Maximum total patch size in bytes (default: 10240 = 10KB, max: 102400 = 100KB). The total size of the git diff must not exceed this value." }, "description": { "type": "string", "description": "Optional description for this memory that will be shown in the agent prompt" }, "create-orphan": { "type": "boolean", "description": "Create orphaned branch if it doesn't exist (default: true)" }, "wiki": { "type": "boolean", "description": "Use the GitHub Wiki git repository instead of the regular repository. When enabled, files are stored in and read from the wiki, and the agent will be instructed to follow GitHub Wiki markdown syntax (default: false)" }, "allowed-extensions": { "type": "array", "items": { "type": "string" }, "description": "List of allowed file extensions (e.g., [\".json\", \".txt\"]). Default: [\".json\", \".jsonl\", \".txt\", \".md\", \".csv\"]" } }, "additionalProperties": false }, "minItems": 1, "examples": [ [ { "id": "default", "branch-name": "memory/default" }, { "id": "session", "branch-name": "memory/session" } ] ], "maxItems": 10 } ], "examples": [ true, null, { "branch-name": "memory/agent-state" }, [ { "id": "default", "branch-name": "memory/default" }, { "id": "logs", "branch-name": "memory/logs", "max-file-size": 524288 } ] ] } }, "additionalProperties": { "oneOf": [ { "type": "string", "description": "Simple tool string for basic tool configuration" }, { "type": "boolean", "description": "Boolean flag to enable or disable a tool (e.g., safety-prompt: true)" }, { "type": "object", "description": "MCP server configuration object", "properties": { "command": { "type": "string", "description": "Command to execute for stdio MCP server" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments for the command" }, "env": { "type": "object", "patternProperties": { "^[A-Za-z_][A-Za-z0-9_]*$": { "type": "string" } }, "description": "Environment variables" }, "type": { "type": "string", "enum": ["stdio", "http", "remote", "local"], "description": "MCP connection type. Use 'stdio' for command-based or container-based servers, 'http' for HTTP-based servers. 'local' is an alias for 'stdio' and is normalized during parsing." }, "version": { "type": ["string", "number"], "description": "Version of the MCP server" }, "toolsets": { "type": "array", "items": { "type": "string" }, "description": "Toolsets to enable" }, "id": { "type": "string", "description": "URL for HTTP mode MCP servers" }, "headers": { "type": "object", "patternProperties": { "^[A-Za-z0-9_-]+$": { "type": "string" } }, "description": "HTTP headers for HTTP mode" }, "container": { "type": "string", "description": "Container image for the MCP server" }, "entrypointArgs": { "type": "array", "items": { "type": "string" }, "description": "Arguments passed to container entrypoint" }, "registry": { "type": "string", "description": "URI to installation location from MCP registry", "examples": ["https://api.mcp.github.com/v0/servers/microsoft/markitdown", "https://registry.npmjs.org/@my/tool"] }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "List of allowed tool names (restricts which tools from the MCP server can be used)", "examples": [["*"], ["store_memory", "retrieve_memory"], ["create-issue", "add-comment"]] }, "entrypoint": { "type": "string", "description": "Optional entrypoint override for container (equivalent to docker run --entrypoint)", "examples": ["/bin/sh", "/custom/entrypoint.sh", "python"] }, "mounts": { "type": "array", "items": { "type": "string", "pattern": "^[^:]+:[^:]+:(ro|rw)$" }, "description": "Volume mounts for container in format 'source:dest:mode' where mode is 'ro' or 'rw'", "examples": [["/tmp/data:/data:ro"], ["/workspace:/workspace:rw", "/config:/config:ro"]] } }, "additionalProperties": true } ] } }, "command": { "type": "string", "description": "Command name for the workflow" }, "cache": { "description": "Cache configuration for workflow (uses actions/cache syntax)", "oneOf": [ { "type": "object", "description": "Single cache configuration", "properties": { "key": { "type": "string", "description": "An explicit key for restoring and saving the cache" }, "path": { "oneOf": [ { "type": "string", "description": "A single path to cache" }, { "type": "array", "description": "Multiple paths to cache", "items": { "type": "string" } } ], "description": "File path or directory to cache for faster workflow execution. Can be a single path or an array of paths to cache multiple locations." }, "restore-keys": { "oneOf": [ { "type": "string", "description": "A single restore key" }, { "type": "array", "description": "Multiple restore keys", "items": { "type": "string" } } ], "description": "Optional list of fallback cache key patterns to use if exact cache key is not found. Enables partial cache restoration for better performance." }, "upload-chunk-size": { "type": "integer", "description": "The chunk size used to split up large files during upload, in bytes" }, "fail-on-cache-miss": { "type": "boolean", "description": "Fail the workflow if cache entry is not found" }, "lookup-only": { "type": "boolean", "description": "If true, only checks if cache entry exists and skips download" }, "name": { "type": "string", "description": "Optional custom name for the cache step (overrides auto-generated name)" } }, "required": ["key", "path"], "additionalProperties": false, "examples": [ { "key": "node-modules-${{ hashFiles('package-lock.json') }}", "path": "node_modules", "restore-keys": ["node-modules-"] }, { "key": "build-cache-${{ github.sha }}", "path": ["dist", ".cache"], "restore-keys": "build-cache-", "fail-on-cache-miss": false } ] }, { "type": "array", "description": "Multiple cache configurations", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "An explicit key for restoring and saving the cache" }, "path": { "oneOf": [ { "type": "string", "description": "A single path to cache" }, { "type": "array", "description": "Multiple paths to cache", "items": { "type": "string" } } ], "description": "File path or directory to cache for faster workflow execution. Can be a single path or an array of paths to cache multiple locations." }, "restore-keys": { "oneOf": [ { "type": "string", "description": "A single restore key" }, { "type": "array", "description": "Multiple restore keys", "items": { "type": "string" } } ], "description": "Optional list of fallback cache key patterns to use if exact cache key is not found. Enables partial cache restoration for better performance." }, "upload-chunk-size": { "type": "integer", "description": "The chunk size used to split up large files during upload, in bytes" }, "fail-on-cache-miss": { "type": "boolean", "description": "Fail the workflow if cache entry is not found" }, "lookup-only": { "type": "boolean", "description": "If true, only checks if cache entry exists and skips download" }, "name": { "type": "string", "description": "Optional custom name for the cache step (overrides auto-generated name)" } }, "required": ["key", "path"], "additionalProperties": false } } ] }, "safe-outputs": { "type": "object", "$comment": "Required if workflow creates or modifies GitHub resources. Operations requiring safe-outputs: autofix-code-scanning-alert, add-comment, add-labels, add-reviewer, assign-milestone, assign-to-agent, assign-to-user, close-discussion, close-issue, close-pull-request, create-agent-session, create-agent-task (deprecated, use create-agent-session), create-code-scanning-alert, create-discussion, create-issue, create-project, create-project-status-update, create-pull-request, create-pull-request-review-comment, dispatch-workflow, hide-comment, link-sub-issue, mark-pull-request-as-ready-for-review, missing-data, missing-tool, noop, push-to-pull-request-branch, remove-labels, reply-to-pull-request-review-comment, resolve-pull-request-review-thread, set-issue-type, submit-pull-request-review, threat-detection, unassign-from-user, update-discussion, update-issue, update-project, update-pull-request, update-release, upload-asset. See documentation for complete details.", "description": "Safe output processing configuration that automatically creates GitHub issues, comments, and pull requests from AI workflow output without requiring write permissions in the main job", "examples": [ { "create-issue": { "title-prefix": "[AI] ", "labels": ["automation", "ai-generated"] } }, { "create-pull-request": { "title-prefix": "[Bot] ", "labels": ["bot"] } }, { "add-comment": null, "create-issue": null } ], "properties": { "allowed-domains": { "type": "array", "description": "List of allowed domains for URL redaction in safe output handlers. Supports ecosystem identifiers (e.g., \"python\", \"node\", \"default-safe-outputs\") like network.allowed. These domains are unioned with the engine defaults and network.allowed when computing the final allowed domain set. localhost and github.com are always included.", "items": { "type": "string" } }, "allowed-github-references": { "type": "array", "description": "List of allowed repositories for GitHub references (e.g., #123 or owner/repo#456). Use 'repo' to allow current repository. References to other repositories will be escaped with backticks. If not specified, all references are allowed.", "items": { "type": "string" }, "examples": [["repo"], ["repo", "octocat/hello-world"], ["microsoft/vscode", "microsoft/typescript"], ["repo", "${{ github.repository }}"]] }, "create-issue": { "oneOf": [ { "type": "object", "description": "Configuration for automatically creating GitHub issues from AI workflow output. The main job does not need 'issues: write' permission.", "properties": { "title-prefix": { "type": "string", "description": "Optional prefix to add to the beginning of the issue title (e.g., '[ai] ' or '[analysis] ')" }, "labels": { "type": "array", "description": "Optional list of labels to automatically attach to created issues (e.g., ['automation', 'ai-generated'])", "items": { "type": "string" } }, "allowed-labels": { "type": "array", "description": "Optional list of allowed labels that can be used when creating issues. If omitted, any labels are allowed (including creating new ones). When specified, the agent can only use labels from this list.", "items": { "type": "string" } }, "assignees": { "oneOf": [ { "type": "string", "description": "Single GitHub username to assign the created issue to (e.g., 'user1' or 'copilot'). Use 'copilot' to assign to GitHub Copilot using the @copilot special value." }, { "type": "array", "description": "List of GitHub usernames to assign the created issue to (e.g., ['user1', 'user2', 'copilot']). Use 'copilot' to assign to GitHub Copilot using the @copilot special value.", "items": { "type": "string" } } ], "description": "GitHub usernames to assign the created issue to. Can be a single username string or array of usernames. Use 'copilot' to assign to GitHub Copilot." }, "max": { "description": "Maximum number of issues to create (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository issue creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that issues can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the issue in. The target repository (current or target-repo) is always implicitly allowed." }, "expires": { "oneOf": [ { "type": "integer", "minimum": 1, "description": "Number of days until expires" }, { "type": "string", "pattern": "^[0-9]+[hHdDwWmMyY]$", "description": "Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for hour values" }, { "type": "boolean", "enum": [false], "description": "Set to false to explicitly disable expiration" } ], "description": "Time until the issue expires and should be automatically closed. Supports integer (days), relative time format, or false to disable expiration. Minimum duration: 2 hours. When set, a maintenance workflow will be generated." }, "group": { "type": "boolean", "description": "If true, group issues as sub-issues under a parent issue. The workflow ID is used as the group identifier. Parent issues are automatically created and managed, with a maximum of 64 sub-issues per parent.", "default": false }, "close-older-issues": { "type": "boolean", "description": "When true, automatically close older issues with the same workflow-id marker as 'not planned' with a comment linking to the new issue. Searches for issues containing the workflow-id marker in their body. Maximum 10 issues will be closed. Only runs if issue creation succeeds.", "default": false }, "close-older-key": { "type": "string", "description": "Optional explicit deduplication key for close-older matching. When set, a `` marker is embedded in the issue body and used as the primary key for searching and filtering older issues instead of the workflow-id markers. This gives deterministic isolation across caller workflows and is stable across workflow renames. The value is normalized to identifier style (lowercase alphanumeric, dashes, underscores).", "minLength": 1, "pattern": "\\S" }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added to the issue. When false, the visible footer content is omitted but XML markers (workflow-id, tracker-id, metadata) are still included for searchability. Defaults to true.", "default": true }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "title-prefix": "[ca] ", "labels": ["automation", "dependencies"], "assignees": "copilot" }, { "title-prefix": "[duplicate-code] ", "labels": ["code-quality", "automated-analysis"], "assignees": "copilot" }, { "allowed-repos": ["org/other-repo", "org/another-repo"], "title-prefix": "[cross-repo] " }, { "title-prefix": "[weekly-report] ", "labels": ["report", "automation"], "close-older-issues": true } ] }, { "type": "null", "description": "Enable issue creation with default configuration" } ], "description": "Enable AI agents to create GitHub issues from workflow output. Supports title prefixes, automatic labeling, assignees, and cross-repository creation. Does not require 'issues: write' permission." }, "create-agent-task": { "oneOf": [ { "type": "object", "description": "DEPRECATED: Use 'create-agent-session' instead. Configuration for creating GitHub Copilot coding agent sessions from agentic workflow output using gh agent-task CLI. The main job does not need write permissions.", "deprecated": true, "properties": { "base": { "type": "string", "description": "Base branch for the agent session pull request. Defaults to the current branch or repository default branch." }, "max": { "description": "Maximum number of agent sessions to create (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository agent session creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that agent sessions can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the agent session in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable agent session creation with default configuration" } ], "description": "Enable creation of GitHub Copilot coding agent tasks from workflow output. Allows workflows to spawn new agent sessions for follow-up work." }, "create-agent-session": { "oneOf": [ { "type": "object", "description": "Configuration for creating GitHub Copilot coding agent sessions from agentic workflow output using gh agent-task CLI. The main job does not need write permissions.", "properties": { "base": { "type": "string", "description": "Base branch for the agent session pull request. Defaults to the current branch or repository default branch." }, "max": { "description": "Maximum number of agent sessions to create (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository agent session creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that agent sessions can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the agent session in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable agent session creation with default configuration" } ], "description": "Enable creation of GitHub Copilot coding agent sessions from workflow output. Allows workflows to start interactive agent conversations." }, "update-project": { "oneOf": [ { "type": "object", "description": "Configuration for managing GitHub Projects boards. Enable agents to add issues and pull requests to projects, update custom field values (status, priority, effort, dates), create project fields and views. By default it is update-only: if the project does not exist, the job fails with instructions to create it. To allow workflows to create missing projects, explicitly opt in via agent output field create_if_missing=true. Requires a Personal Access Token (PAT) or GitHub App token with Projects permissions (default GITHUB_TOKEN cannot be used). Agent output includes: project (full URL or temporary project ID like aw_XXXXXXXXXXXX or #aw_XXXXXXXXXXXX from create_project), content_type (issue|pull_request|draft_issue), content_number, fields, create_if_missing. For specialized operations, agent can also provide: operation (create_fields|create_view), field_definitions (array of field configs when operation=create_fields), view (view config object when operation=create_view).", "required": ["project"], "properties": { "max": { "description": "Maximum number of project operations to perform (default: 10). Each operation may add a project item, or update its fields. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "project": { "type": "string", "description": "Target project URL for update-project operations. This is required in the configuration for documentation purposes. Agent messages MUST explicitly include the project field in their output - the configured value is not used as a fallback. Must be a valid GitHub Projects v2 URL.", "pattern": "^https://github\\.com/(users|orgs)/([^/]+|<[A-Z_]+>)/projects/(\\d+|<[A-Z_]+>)$", "examples": ["https://github.com/orgs/myorg/projects/123", "https://github.com/users/username/projects/456"] }, "target-repo": { "description": "Default repository in format 'owner/repo' for cross-repository content resolution. When specified, the agent can use 'target_repo' in agent output to resolve issues or PRs from this repository. Wildcards ('*') are not allowed. Supports GitHub Actions expression syntax (e.g., '${{ vars.TARGET_REPO }}').", "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$" }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to owner/repo at runtime" } ] }, "allowed-repos": { "type": "array", "items": { "oneOf": [ { "type": "string", "pattern": "^(\\*|([a-zA-Z0-9_.-]+|\\*)/([a-zA-Z0-9_.-]+|\\*))$" }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to owner/repo at runtime" } ] }, "description": "List of additional repositories in format 'owner/repo' allowed for cross-repository content resolution via 'target_repo'. The target-repo (or current repo) is always implicitly allowed. Supports wildcard patterns (e.g., 'org/*', '*/repo', '*') and GitHub Actions expression syntax for individual entries." }, "views": { "type": "array", "description": "Optional array of project views to create. Each view must have a name and layout. Views are created during project setup.", "items": { "type": "object", "description": "View configuration for creating project views", "required": ["name", "layout"], "properties": { "name": { "type": "string", "description": "The name of the view (e.g., 'Sprint Board', 'Roadmap')" }, "layout": { "type": "string", "enum": ["table", "board", "roadmap"], "description": "The layout type of the view" }, "filter": { "type": "string", "description": "Optional filter query for the view (e.g., 'is:issue is:open', 'label:bug')" }, "visible-fields": { "type": "array", "items": { "type": "integer" }, "description": "Optional array of field IDs that should be visible in the view (table/board only, not applicable to roadmap)" }, "description": { "type": "string", "description": "Optional human description for the view. Not supported by the GitHub Views API and may be ignored." } }, "additionalProperties": false } }, "field-definitions": { "type": "array", "description": "Optional array of project custom fields to create up-front.", "items": { "type": "object", "required": ["name", "data-type"], "properties": { "name": { "type": "string", "description": "The field name to create (e.g., 'status', 'priority')" }, "data-type": { "type": "string", "enum": ["DATE", "TEXT", "NUMBER", "SINGLE_SELECT", "ITERATION"], "description": "The GitHub Projects v2 custom field type" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Options for SINGLE_SELECT fields. GitHub does not support adding options later." } }, "additionalProperties": false } }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "max": 15 }, { "github-token": "${{ secrets.PROJECT_GITHUB_TOKEN }}", "max": 15 } ] }, { "type": "null", "description": "Enable project management with default configuration (max=10)" } ], "description": "Enable AI agents to add items to GitHub Projects, update custom fields, and manage project structure. Use this for organizing work into projects with status tracking, priority management, and custom metadata." }, "create-project": { "oneOf": [ { "type": "object", "description": "Configuration for creating new GitHub Projects boards. Enables agents to create new project boards with optional custom fields, views, and an initial item. Requires a Personal Access Token (PAT) or GitHub App token with Projects write permission (default GITHUB_TOKEN cannot be used). Agent output includes: title (project name), owner (org/user login, uses default if omitted), owner_type ('org' or 'user'), optional item_url (issue to add as first item), and optional field_definitions. Returns a temporary project ID for use in subsequent update_project operations.", "properties": { "max": { "description": "Maximum number of create operations to perform (default: 1). Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Must have Projects write permission. Overrides global github-token if specified." }, "target-owner": { "type": "string", "description": "Optional default target owner (organization or user login, e.g., 'myorg' or 'username') for the new project. If specified, the agent can omit the owner field in the tool call and this default will be used. The agent can still override by providing an owner in the tool call." }, "title-prefix": { "type": "string", "description": "Optional prefix for auto-generated project titles (default: 'Project'). When the agent doesn't provide a title, the project title is auto-generated as ': ' or ' #' based on the issue context." }, "views": { "type": "array", "description": "Optional array of project views to create automatically after project creation. Each view must have a name and layout. Views are created immediately after the project is created.", "items": { "type": "object", "description": "View configuration for creating project views", "required": ["name", "layout"], "properties": { "name": { "type": "string", "description": "The name of the view (e.g., 'Sprint Board', 'Roadmap')" }, "layout": { "type": "string", "enum": ["table", "board", "roadmap"], "description": "The layout type of the view" }, "filter": { "type": "string", "description": "Optional filter query for the view (e.g., 'is:issue is:open', 'label:bug')" }, "visible-fields": { "type": "array", "items": { "type": "integer" }, "description": "Optional array of field IDs that should be visible in the view (table/board only, not applicable to roadmap)" }, "description": { "type": "string", "description": "Optional human description for the view. Not supported by the GitHub Views API and may be ignored." } }, "additionalProperties": false } }, "field-definitions": { "type": "array", "description": "Optional array of project custom fields to create automatically after project creation.", "items": { "type": "object", "required": ["name", "data-type"], "properties": { "name": { "type": "string", "description": "The field name to create (e.g., 'Priority', 'Classification')" }, "data-type": { "type": "string", "enum": ["DATE", "TEXT", "NUMBER", "SINGLE_SELECT", "ITERATION"], "description": "The GitHub Projects v2 custom field type" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Options for SINGLE_SELECT fields. GitHub does not support adding options later." } }, "additionalProperties": false } }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable project creation with default configuration (max=1)" } ], "default": { "max": 1 }, "description": "Enable AI agents to create new GitHub Projects for organizing and tracking work across issues and pull requests." }, "create-project-status-update": { "oneOf": [ { "type": "object", "description": "Configuration for posting status updates to GitHub Projects. Status updates provide stakeholder communication about project progress, health, and timeline. Each update appears in the project's Updates tab and creates a historical record. Requires a Personal Access Token (PAT) or GitHub App token with Projects read & write permission (default GITHUB_TOKEN cannot be used). Typically used by scheduled workflows or orchestrators to post regular progress summaries with status indicators (on-track, at-risk, off-track, complete, inactive), dates, and progress details.", "required": ["project"], "properties": { "max": { "description": "Maximum number of status updates to create (default: 1). Typically 1 per orchestrator run. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified. Must have Projects: Read+Write permission." }, "project": { "type": "string", "description": "Target project URL for status update operations. This is required in the configuration for documentation purposes. Agent messages MUST explicitly include the project field in their output - the configured value is not used as a fallback. Must be a valid GitHub Projects v2 URL.", "pattern": "^https://github\\.com/(users|orgs)/([^/]+|<[A-Z_]+>)/projects/(\\d+|<[A-Z_]+>)$", "examples": ["https://github.com/orgs/myorg/projects/123", "https://github.com/users/username/projects/456"] }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "max": 1 }, { "github-token": "${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}", "max": 1 } ] }, { "type": "null", "description": "Enable project status updates with default configuration (max=1)" } ], "description": "Enable AI agents to post status updates to GitHub Projects for progress tracking and stakeholder communication." }, "create-discussion": { "oneOf": [ { "type": "object", "description": "Configuration for creating GitHub discussions from agentic workflow output", "properties": { "title-prefix": { "type": "string", "description": "Optional prefix for the discussion title" }, "category": { "type": ["string", "number"], "description": "Optional discussion category. Can be a category ID (string or numeric value), category name, or category slug/route. If not specified, uses the first available category. Matched first against category IDs, then against category names, then against category slugs. Numeric values are automatically converted to strings at runtime.", "examples": ["General", "audits", 123456789] }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Optional list of labels to attach to created discussions. Also used for matching when close-older-discussions is enabled - discussions must have ALL specified labels (AND logic)." }, "allowed-labels": { "type": "array", "description": "Optional list of allowed labels that can be used when creating discussions. If omitted, any labels are allowed (including creating new ones). When specified, the agent can only use labels from this list.", "items": { "type": "string" } }, "max": { "description": "Maximum number of discussions to create (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository discussion creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that discussions can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the discussion in. The target repository (current or target-repo) is always implicitly allowed." }, "close-older-discussions": { "type": "boolean", "description": "When true, automatically close older discussions matching the same title prefix or labels as 'outdated' with a comment linking to the new discussion. Requires title-prefix or labels to be set. Maximum 10 discussions will be closed. Only runs if discussion creation succeeds. When fallback-to-issue is enabled and discussion creation fails, older issues will be closed instead.", "default": false }, "close-older-key": { "type": "string", "description": "Optional explicit deduplication key for close-older matching. When set, a `` marker is embedded in the discussion body and used as the primary key for searching and filtering older discussions instead of the workflow-id markers. This gives deterministic isolation across caller workflows and is stable across workflow renames. The value is normalized to identifier style (lowercase alphanumeric, dashes, underscores).", "minLength": 1, "pattern": "\\S" }, "fallback-to-issue": { "type": "boolean", "description": "When true (default), fallback to creating an issue if discussion creation fails due to permissions. The fallback issue will include a note indicating it was intended to be a discussion. If close-older-discussions is enabled, the close-older-issues logic will be applied to the fallback issue.", "default": true }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added to the discussion. When false, the visible footer content is omitted but XML markers (workflow-id, tracker-id, metadata) are still included for searchability. Defaults to true.", "default": true }, "expires": { "oneOf": [ { "type": "integer", "minimum": 1, "description": "Number of days until expires" }, { "type": "string", "pattern": "^[0-9]+[hHdDwWmMyY]$", "description": "Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for hour values" }, { "type": "boolean", "enum": [false], "description": "Set to false to explicitly disable expiration" } ], "default": 7, "description": "Time until the discussion expires and should be automatically closed. Supports integer (days), relative time format like '2h' (2 hours), '7d' (7 days), '2w' (2 weeks), '1m' (1 month), '1y' (1 year), or false to disable expiration. Minimum duration: 2 hours. When set, a maintenance workflow will be generated. Defaults to 7 days if not specified." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "category": "audits" }, { "title-prefix": "[copilot-agent-analysis] ", "category": "audits", "max": 1 }, { "category": "General" }, { "title-prefix": "[weekly-report] ", "category": "reports", "close-older-discussions": true }, { "labels": ["weekly-report", "automation"], "category": "reports", "close-older-discussions": true }, { "allowed-repos": ["org/other-repo"], "category": "General" } ] }, { "type": "null", "description": "Enable discussion creation with default configuration" } ], "description": "Enable AI agents to create GitHub Discussions from workflow output. Supports categorization, labeling, and automatic closure of older discussions. Does not require 'discussions: write' permission." }, "close-discussion": { "oneOf": [ { "type": "object", "description": "Configuration for closing GitHub discussions with comment and resolution from agentic workflow output", "properties": { "required-labels": { "type": "array", "items": { "type": "string" }, "description": "Only close discussions that have all of these labels" }, "required-title-prefix": { "type": "string", "description": "Only close discussions with this title prefix" }, "required-category": { "type": "string", "description": "Only close discussions in this category" }, "target": { "type": "string", "description": "Target for closing: 'triggering' (default, current discussion), or '*' (any discussion with discussion_number field)" }, "max": { "description": "Maximum number of discussions to close (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "required-category": "Ideas" }, { "required-labels": ["resolved", "completed"], "max": 1 } ] }, { "type": "null", "description": "Enable discussion closing with default configuration" } ], "description": "Enable AI agents to close GitHub Discussions based on workflow analysis or conditions." }, "update-discussion": { "oneOf": [ { "type": "object", "description": "Configuration for updating GitHub discussions from agentic workflow output", "properties": { "target": { "type": "string", "description": "Target for updates: 'triggering' (default), '*' (any discussion), or explicit discussion number" }, "title": { "type": "null", "description": "Allow updating discussion title - presence of key indicates field can be updated" }, "body": { "type": "null", "description": "Allow updating discussion body - presence of key indicates field can be updated" }, "labels": { "type": "null", "description": "Allow updating discussion labels - presence of key indicates field can be updated" }, "allowed-labels": { "type": "array", "items": { "type": "string" }, "description": "Optional list of allowed labels. If omitted, any labels are allowed (including creating new ones)." }, "max": { "description": "Maximum number of discussions to update (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 256 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository discussion updates. Takes precedence over trial target repo settings." }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added when updating the discussion body. When false, the visible footer content is omitted. Defaults to true. Only applies when 'body' is enabled.", "default": true }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." } }, "additionalProperties": false }, { "type": "null", "description": "Enable discussion updating with default configuration" } ], "description": "Enable AI agents to edit and update existing GitHub Discussion content, titles, and metadata." }, "close-issue": { "oneOf": [ { "type": "object", "description": "Configuration for closing GitHub issues with comment from agentic workflow output", "properties": { "required-labels": { "type": "array", "items": { "type": "string" }, "description": "Only close issues that have all of these labels" }, "required-title-prefix": { "type": "string", "description": "Only close issues with this title prefix" }, "target": { "type": "string", "description": "Target for closing: 'triggering' (default, current issue), or '*' (any issue with issue_number field)" }, "max": { "description": "Maximum number of issues to close (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that issues can be closed in. When specified, the agent can use a 'repo' field in the output to specify which repository to close the issue in. The target repository (current or target-repo) is always implicitly allowed." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "required-title-prefix": "[refactor] " }, { "required-labels": ["automated", "stale"], "max": 10 } ] }, { "type": "null", "description": "Enable issue closing with default configuration" } ], "description": "Enable AI agents to close GitHub issues based on workflow analysis, resolution detection, or automated triage." }, "close-pull-request": { "oneOf": [ { "type": "object", "description": "Configuration for closing GitHub pull requests without merging, with comment from agentic workflow output", "properties": { "required-labels": { "type": "array", "items": { "type": "string" }, "description": "Only close pull requests that have any of these labels" }, "required-title-prefix": { "type": "string", "description": "Only close pull requests with this title prefix" }, "target": { "type": "string", "description": "Target for closing: 'triggering' (default, current PR), or '*' (any PR with pull_request_number field)" }, "max": { "description": "Maximum number of pull requests to close (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "required-title-prefix": "[bot] " }, { "required-labels": ["automated", "outdated"], "max": 5 } ] }, { "type": "null", "description": "Enable pull request closing with default configuration" } ], "description": "Enable AI agents to close pull requests based on workflow analysis or automated review decisions." }, "mark-pull-request-as-ready-for-review": { "oneOf": [ { "type": "object", "description": "Configuration for marking draft pull requests as ready for review, with comment from agentic workflow output", "properties": { "required-labels": { "type": "array", "items": { "type": "string" }, "description": "Only mark pull requests that have any of these labels" }, "required-title-prefix": { "type": "string", "description": "Only mark pull requests with this title prefix" }, "target": { "type": "string", "description": "Target for marking: 'triggering' (default, current PR), or '*' (any PR with pull_request_number field)" }, "max": { "description": "Maximum number of pull requests to mark as ready (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "required-title-prefix": "[bot] " }, { "required-labels": ["automated", "ready"], "max": 1 } ] }, { "type": "null", "description": "Enable marking pull requests as ready for review with default configuration" } ], "description": "Enable AI agents to mark draft pull requests as ready for review when criteria are met." }, "add-comment": { "oneOf": [ { "type": "object", "description": "Configuration for automatically creating GitHub issue or pull request comments from AI workflow output. The main job does not need write permissions.", "properties": { "max": { "description": "Maximum number of comments to create (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for comments: 'triggering' (default), '*' (any issue), or explicit issue number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository comments. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that comments can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the comment in. The target repository (current or target-repo) is always implicitly allowed." }, "discussion": { "type": "boolean", "const": true, "description": "DEPRECATED: This field is deprecated and will be removed in a future version. The add_comment handler now automatically detects whether to target discussions based on context (discussion/discussion_comment events) or the item_number field provided by the agent. Remove this field from your workflow configuration.", "deprecated": true }, "hide-older-comments": { "type": "boolean", "description": "When true, minimizes/hides all previous comments from the same agentic workflow (identified by tracker-id) before creating the new comment. Default: false." }, "allowed-reasons": { "type": "array", "description": "List of allowed reasons for hiding older comments when hide-older-comments is enabled. Default: all reasons allowed (spam, abuse, off_topic, outdated, resolved).", "items": { "type": "string", "enum": ["spam", "abuse", "off_topic", "outdated", "resolved"] } }, "discussions": { "type": "boolean", "description": "Controls whether the workflow requests discussions:write permission for add-comment and includes discussions in the event trigger condition. Default: true (includes discussions:write). Set to false if your GitHub App lacks Discussions permission to prevent 422 errors during token generation." }, "issues": { "type": "boolean", "description": "Controls whether the workflow requests issues:write permission for add-comment and includes issues in the event trigger condition. Default: true (includes issues:write). Set to false to disable issue commenting." }, "pull-requests": { "type": "boolean", "description": "Controls whether the workflow requests pull-requests:write permission for add-comment and includes pull requests in the event trigger condition. Default: true (includes pull-requests:write). Set to false to disable pull request commenting." }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added to the comment. When false, the visible footer content is omitted but XML markers (workflow-id, metadata) are still included for searchability. Defaults to true.", "default": true }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "max": 1, "target": "*" }, { "max": 3 } ] }, { "type": "null", "description": "Enable issue comment creation with default configuration" } ], "description": "Enable AI agents to add comments to GitHub issues, pull requests, or discussions. Supports templating, cross-repository commenting, and automatic mentions." }, "create-pull-request": { "oneOf": [ { "type": "object", "description": "Configuration for creating GitHub pull requests from agentic workflow output. Supports creating multiple PRs in a single run when max > 1.", "properties": { "max": { "description": "Maximum number of pull requests to create (default: 1). Each PR requires distinct changes on a separate branch. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "title-prefix": { "type": "string", "description": "Optional prefix for the pull request title" }, "labels": { "type": "array", "description": "Optional list of labels to attach to the pull request", "items": { "type": "string" } }, "allowed-labels": { "type": "array", "description": "Optional list of allowed labels that can be used when creating pull requests. If omitted, any labels are allowed (including creating new ones). When specified, the agent can only use labels from this list.", "items": { "type": "string" } }, "reviewers": { "oneOf": [ { "type": "string", "description": "Single reviewer username to assign to the pull request. Use 'copilot' to request a code review from GitHub Copilot using the copilot-pull-request-reviewer[bot]." }, { "type": "array", "description": "List of reviewer usernames to assign to the pull request. Use 'copilot' to request a code review from GitHub Copilot using the copilot-pull-request-reviewer[bot].", "items": { "type": "string" } } ], "description": "Optional reviewer(s) to assign to the pull request. Accepts either a single string or an array of usernames. Use 'copilot' to request a code review from GitHub Copilot." }, "draft": { "allOf": [ { "$ref": "#/$defs/templatable_boolean" } ], "description": "Whether to create pull request as draft (defaults to true). Accepts a boolean or a GitHub Actions expression.", "default": true }, "if-no-changes": { "type": "string", "enum": ["warn", "error", "ignore"], "description": "Behavior when no changes to push: 'warn' (default - log warning but succeed), 'error' (fail the action), or 'ignore' (silent success)" }, "allow-empty": { "type": "boolean", "description": "When true, allows creating a pull request without any initial changes or git patch. This is useful for preparing a feature branch that an agent can push changes to later. The branch will be created from the base branch without applying any patch. Defaults to false." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository pull request creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that pull requests can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the pull request in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "expires": { "oneOf": [ { "type": "integer", "minimum": 1, "description": "Number of days until expires" }, { "type": "string", "pattern": "^[0-9]+[hHdDwWmMyY]$", "description": "Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for hour values" } ], "description": "Time until the pull request expires and should be automatically closed (only for same-repo PRs without target-repo). Supports integer (days) or relative time format. Minimum duration: 2 hours." }, "auto-merge": { "type": "boolean", "description": "Enable auto-merge for the pull request. When enabled, the PR will be automatically merged once all required checks pass and required approvals are met. Defaults to false.", "default": false }, "base-branch": { "type": "string", "description": "Base branch for the pull request. Defaults to the workflow's branch (github.ref_name) if not specified. Useful for cross-repository PRs targeting non-default branches (e.g., 'vnext', 'release/v1.0')." }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added to the pull request. When false, the visible footer content is omitted but XML markers (workflow-id, tracker-id, metadata) are still included for searchability. Defaults to true.", "default": true }, "fallback-as-issue": { "type": "boolean", "description": "Controls the fallback behavior when pull request creation fails. When true (default), an issue is created as a fallback with the patch content. When false, no issue is created and the workflow fails with an error. Setting to false also removes the issues:write permission requirement.", "default": true }, "github-token-for-extra-empty-commit": { "type": "string", "description": "Token used to push an empty commit after PR creation to trigger CI events. Works around the GITHUB_TOKEN limitation where pushes don't trigger workflow runs. Defaults to the magic secret GH_AW_CI_TRIGGER_TOKEN if set in the repository. Use a secret expression (e.g. '${{ secrets.CI_TOKEN }}') for a custom token, or 'app' for GitHub App auth." }, "protected-files": { "type": "string", "enum": ["blocked", "allowed", "fallback-to-issue"], "description": "Controls protected-file protection. blocked (default): hard-block any patch that modifies package manifests (e.g. package.json, go.mod), engine instruction files (e.g. AGENTS.md, CLAUDE.md) or .github/ files. allowed: allow all changes. fallback-to-issue: push the branch but create a review issue instead of a PR, so a human can review the manifest changes before merging.", "default": "blocked" }, "allowed-files": { "type": "array", "items": { "type": "string" }, "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern \u2014 files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)." }, "preserve-branch-name": { "type": "boolean", "description": "When true, the random salt suffix is not appended to the agent-specified branch name. Invalid characters are still replaced for security, and casing is always preserved regardless of this setting. Useful when the target repository enforces branch naming conventions (e.g. Jira keys in uppercase such as 'bugfix/BR-329-red'). Defaults to false.", "default": false }, "excluded-files": { "type": "array", "items": { "type": "string" }, "description": "List of glob patterns for files to exclude from the patch. Each pattern is passed to `git format-patch` as a `:(exclude)` magic pathspec, so matching files are stripped by git at generation time and will not appear in the commit. Excluded files are also not subject to `allowed-files` or `protected-files` checks. Supports * (any characters except /) and ** (any characters including /)." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false, "examples": [ { "title-prefix": "[docs] ", "labels": ["documentation", "automation"], "reviewers": "copilot", "draft": false }, { "title-prefix": "[security-fix] ", "labels": ["security", "automated-fix"], "reviewers": "copilot" } ] }, { "type": "null", "description": "Enable pull request creation with default configuration" } ], "description": "Enable AI agents to create GitHub pull requests from workflow-generated code changes, patches, or analysis results." }, "create-pull-request-review-comment": { "oneOf": [ { "type": "object", "description": "Configuration for creating GitHub pull request review comments from agentic workflow output", "properties": { "max": { "description": "Maximum number of review comments to create (default: 10) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "side": { "type": "string", "description": "Side of the diff for comments: 'LEFT' or 'RIGHT' (default: 'RIGHT')", "enum": ["LEFT", "RIGHT"] }, "target": { "type": "string", "description": "Target for review comments: 'triggering' (default, only on triggering PR), '*' (any PR, requires pull_request_number in agent output), or explicit PR number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository PR review comments. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that PR review comments can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the review comment in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable PR review comment creation with default configuration" } ], "description": "Enable AI agents to add review comments to specific lines in pull request diffs during code review workflows." }, "submit-pull-request-review": { "oneOf": [ { "type": "object", "description": "Configuration for submitting a consolidated PR review with a status decision (APPROVE, REQUEST_CHANGES, COMMENT). All create-pull-request-review-comment outputs are collected and submitted as part of this review.", "properties": { "max": { "description": "Maximum number of reviews to submit (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "footer": { "oneOf": [ { "type": "boolean", "description": "Controls whether AI-generated footer is added to the review body. true maps to 'always', false maps to 'none'." }, { "type": "string", "enum": ["always", "none", "if-body"], "description": "Controls when AI-generated footer is added to the review body: 'always' (default), 'none' (never), or 'if-body' (only when review has body text)." } ], "description": "Controls when AI-generated footer is added to the review body. Accepts boolean (true/false) or string ('always', 'none', 'if-body'). The 'if-body' mode is useful for clean approval reviews without body text. Defaults to 'always'." }, "target": { "type": "string", "description": "Target PR for the review: 'triggering' (default, current PR), '*' (any PR, requires pull_request_number in agent output), or explicit PR number (e.g. ${{ github.event.inputs.pr_number }}). Required when workflow is not triggered by a pull request (e.g. workflow_dispatch)." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository PR review submission. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that PR reviews can be submitted in. When specified, the agent can use a 'repo' field in the output to specify which repository to submit the review in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable PR review submission with default configuration" } ], "description": "Enable AI agents to submit consolidated pull request reviews with a status decision. Works with create-pull-request-review-comment to batch inline comments into a single review." }, "reply-to-pull-request-review-comment": { "oneOf": [ { "type": "object", "description": "Configuration for replying to existing pull request review comments", "properties": { "max": { "description": "Maximum number of replies to create (default: 10) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for replies: 'triggering' (default), '*' (any PR), or explicit PR number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository operations" }, "allowed-repos": { "type": "array", "description": "List of additional repositories that replies can target", "items": { "type": "string" } }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added to the reply body. When false, the footer is omitted. Defaults to true.", "default": true }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable with default configuration" } ], "description": "Enable AI agents to reply to existing review comments on pull requests." }, "resolve-pull-request-review-thread": { "oneOf": [ { "type": "object", "description": "Configuration for resolving review threads on pull requests. Resolution is scoped to the triggering PR only \u2014 threads on other PRs cannot be resolved.", "properties": { "max": { "description": "Maximum number of review threads to resolve (default: 10) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable review thread resolution with default configuration" } ], "description": "Enable AI agents to resolve review threads on the triggering pull request after addressing feedback." }, "create-code-scanning-alert": { "oneOf": [ { "type": "object", "description": "Configuration for creating repository security advisories (SARIF format) from agentic workflow output", "properties": { "max": { "description": "Maximum number of security findings to include (default: unlimited) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "driver": { "type": "string", "description": "Driver name for SARIF tool.driver.name field (default: 'GitHub Agentic Workflows Security Scanner')" }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository code scanning alert creation. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that code scanning alerts can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the alert in. The target repository (current or target-repo) is always implicitly allowed." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable code scanning alert creation with default configuration (unlimited findings)" } ], "description": "Enable AI agents to create GitHub Advanced Security code scanning alerts for detected vulnerabilities or security issues." }, "autofix-code-scanning-alert": { "oneOf": [ { "type": "object", "description": "Configuration for creating autofixes for code scanning alerts", "properties": { "max": { "description": "Maximum number of autofixes to create (default: 10) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable code scanning autofix creation with default configuration (max: 10)" } ], "description": "Enable AI agents to create autofixes for code scanning alerts using the GitHub REST API." }, "add-labels": { "oneOf": [ { "type": "null", "description": "Null configuration allows any labels. Labels will be created if they don't already exist in the repository." }, { "type": "object", "description": "Configuration for adding labels to issues/PRs from agentic workflow output. Labels will be created if they don't already exist in the repository.", "properties": { "allowed": { "type": "array", "description": "Optional list of allowed labels that can be added. Labels will be created if they don't already exist in the repository. If omitted, any labels are allowed (including creating new ones).", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "blocked": { "type": "array", "description": "Optional list of blocked label patterns (supports glob patterns like '~*', '*[bot]'). Labels matching these patterns will be rejected. Applied before allowed list filtering for security.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Optional maximum number of labels to add (default: 3) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for labels: 'triggering' (default), '*' (any issue/PR), or explicit issue/PR number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository label addition. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that labels can be added to. When specified, the agent can use a 'repo' field in the output to specify which repository to add labels to. The target repository (current or target-repo) is always implicitly allowed." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to add labels to GitHub issues or pull requests based on workflow analysis or classification." }, "remove-labels": { "oneOf": [ { "type": "null", "description": "Null configuration allows any labels to be removed." }, { "type": "object", "description": "Configuration for removing labels from issues/PRs from agentic workflow output.", "properties": { "allowed": { "type": "array", "description": "Optional list of allowed labels that can be removed. If omitted, any labels can be removed.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "blocked": { "type": "array", "description": "Optional list of blocked label patterns (supports glob patterns like '~*', '*[bot]'). Labels matching these patterns will be rejected. Applied before allowed list filtering for security.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Optional maximum number of labels to remove (default: 3) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for labels: 'triggering' (default), '*' (any issue/PR), or explicit issue/PR number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository label removal. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that labels can be removed from. When specified, the agent can use a 'repo' field in the output to specify which repository to remove labels from. The target repository (current or target-repo) is always implicitly allowed." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to remove labels from GitHub issues or pull requests." }, "add-reviewer": { "oneOf": [ { "type": "null", "description": "Null configuration allows any reviewers" }, { "type": "object", "description": "Configuration for adding reviewers to pull requests from agentic workflow output", "properties": { "reviewers": { "type": "array", "description": "Optional list of allowed reviewers. If omitted, any reviewers are allowed.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Optional maximum number of reviewers to add (default: 3) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for reviewers: 'triggering' (default), '*' (any PR), or explicit PR number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository reviewer addition. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to request reviews from users or teams on pull requests based on code changes or expertise matching." }, "assign-milestone": { "oneOf": [ { "type": "null", "description": "Null configuration allows assigning any milestones" }, { "type": "object", "description": "Configuration for assigning issues to milestones from agentic workflow output", "properties": { "allowed": { "type": "array", "description": "Optional list of allowed milestone titles that can be assigned. If omitted, any milestones are allowed.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Optional maximum number of milestone assignments (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository milestone assignment. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to assign GitHub milestones to issues or pull requests based on workflow analysis or project planning." }, "assign-to-agent": { "oneOf": [ { "type": "null", "description": "Null configuration uses default agent (copilot)" }, { "type": "object", "description": "Configuration for assigning GitHub Copilot coding agent to issues from agentic workflow output", "properties": { "name": { "type": "string", "description": "Default agent name to assign (default: 'copilot')" }, "model": { "type": "string", "description": "Default AI model to use for the agent (e.g., 'auto', 'claude-sonnet-4.5', 'claude-opus-4.5', 'claude-opus-4.6', 'gpt-5.1-codex-max', 'gpt-5.2-codex'). Defaults to 'auto' if not specified." }, "custom-agent": { "type": "string", "description": "Default custom agent ID to use when assigning custom agents. This is used for specialized agent configurations beyond the standard Copilot agent." }, "custom-instructions": { "type": "string", "description": "Default custom instructions to provide to the agent. These instructions will guide the agent's behavior when working on the task." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "Optional list of allowed agent names. If specified, only these agents can be assigned. When configured, existing agent assignees not in the list are removed while regular user assignees are preserved." }, "max": { "description": "Optional maximum number of agent assignments (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": ["string", "number"], "description": "Target issue/PR to assign agents to. Use 'triggering' (default) for the triggering issue/PR, '*' to require explicit issue_number/pull_number, or a specific issue/PR number. With 'triggering', auto-resolves from github.event.issue.number or github.event.pull_request.number." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository agent assignment. Takes precedence over trial target repo settings." }, "pull-request-repo": { "type": "string", "description": "Target repository where the pull request should be created, in format 'owner/repo'. If omitted, the PR will be created in the same repository as the issue (specified by target-repo or the workflow's repository). This allows issues and code to live in different repositories." }, "allowed-pull-request-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories that pull requests can be created in beyond pull-request-repo. Each entry should be in 'owner/repo' format. The repository specified by pull-request-repo is automatically allowed without needing to be listed here." }, "ignore-if-error": { "type": "boolean", "description": "If true, the workflow continues gracefully when agent assignment fails (e.g., due to missing token or insufficient permissions), logging a warning instead of failing. Default is false. Useful for workflows that should not fail when agent assignment is optional.", "default": false }, "base-branch": { "type": "string", "description": "Base branch for pull request creation in the target repository. Defaults to the target repo's default branch. Only relevant when pull-request-repo is configured." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to assign issues or pull requests to GitHub Copilot (@copilot) for automated handling." }, "assign-to-user": { "oneOf": [ { "type": "null", "description": "Enable user assignment with default configuration" }, { "type": "object", "description": "Configuration for assigning users to issues from agentic workflow output", "properties": { "allowed": { "type": "array", "items": { "type": "string" }, "description": "Optional list of allowed usernames. If specified, only these users can be assigned." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "Optional list of blocked usernames or patterns (e.g., 'copilot', '*[bot]'). Users matching these patterns cannot be assigned. Supports exact matches and glob patterns." }, "max": { "description": "Optional maximum number of user assignments (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": ["string", "number"], "description": "Target issue to assign users to. Use 'triggering' (default) for the triggering issue, '*' to allow any issue, or a specific issue number." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository user assignment. Takes precedence over trial target repo settings." }, "unassign-first": { "type": "boolean", "description": "If true, unassign all current assignees before assigning new ones. Useful for reassigning issues from one user to another (default: false).", "default": false }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of allowed repositories in format 'owner/repo' for cross-repository user assignment operations. Use with 'repo' field in tool calls." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to assign issues or pull requests to specific GitHub users based on workflow logic or expertise matching." }, "unassign-from-user": { "oneOf": [ { "type": "null", "description": "Enable user unassignment with default configuration" }, { "type": "object", "description": "Configuration for removing assignees from issues in agentic workflow output", "properties": { "allowed": { "type": "array", "items": { "type": "string" }, "description": "Optional list of allowed usernames. If specified, only these users can be unassigned." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "Optional list of blocked usernames or patterns (e.g., 'copilot', '*[bot]'). Users matching these patterns cannot be unassigned. Supports exact matches and glob patterns." }, "max": { "description": "Optional maximum number of unassignment operations (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": ["string", "number"], "description": "Target issue to unassign users from. Use 'triggering' (default) for the triggering issue, '*' to allow any issue, or a specific issue number." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository user unassignment. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of allowed repositories in format 'owner/repo' for cross-repository unassignment operations. Use with 'repo' field in tool calls." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to unassign users from issues or pull requests. Useful for reassigning work or removing users from issues." }, "link-sub-issue": { "oneOf": [ { "type": "null", "description": "Enable sub-issue linking with default configuration" }, { "type": "object", "description": "Configuration for linking issues as sub-issues from agentic workflow output", "properties": { "max": { "description": "Maximum number of sub-issue links to create (default: 5) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "parent-required-labels": { "type": "array", "description": "Optional list of labels that parent issues must have to be eligible for linking", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "parent-title-prefix": { "type": "string", "description": "Optional title prefix that parent issues must have to be eligible for linking" }, "sub-required-labels": { "type": "array", "description": "Optional list of labels that sub-issues must have to be eligible for linking", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "sub-title-prefix": { "type": "string", "description": "Optional title prefix that sub-issues must have to be eligible for linking" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository sub-issue linking. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to create hierarchical relationships between issues using GitHub's sub-issue (tasklist) feature." }, "update-issue": { "oneOf": [ { "type": "object", "description": "Configuration for updating GitHub issues from agentic workflow output", "properties": { "status": { "type": "null", "description": "Allow updating issue status (open/closed) - presence of key indicates field can be updated" }, "target": { "type": "string", "description": "Target for updates: 'triggering' (default), '*' (any issue), or explicit issue number" }, "title": { "type": "null", "description": "Allow updating issue title - presence of key indicates field can be updated" }, "body": { "type": ["boolean", "null"], "description": "Allow updating issue body. Set to true to enable body updates, false to disable. For backward compatibility, null (body:) also enables body updates.", "default": true }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added when updating the issue body. When false, the visible footer content is omitted but XML markers are still included. Defaults to true. Only applies when 'body' is enabled.", "default": true }, "max": { "description": "Maximum number of issues to update (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 256 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository issue updates. Takes precedence over trial target repo settings." }, "title-prefix": { "type": "string", "description": "Required prefix for issue title. Only issues with this title prefix can be updated." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that issues can be updated in. When specified, the agent can use a 'repo' field in the output to specify which repository to update the issue in. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable issue updating with default configuration" } ], "description": "Enable AI agents to edit and update existing GitHub issue content, titles, labels, assignees, and metadata." }, "update-pull-request": { "oneOf": [ { "type": "object", "description": "Configuration for updating GitHub pull requests from agentic workflow output. Both title and body updates are enabled by default.", "properties": { "target": { "type": "string", "description": "Target for updates: 'triggering' (default), '*' (any PR), or explicit PR number" }, "title": { "type": "boolean", "description": "Allow updating pull request title - defaults to true, set to false to disable" }, "body": { "type": "boolean", "description": "Allow updating pull request body - defaults to true, set to false to disable" }, "operation": { "type": "string", "description": "Default operation for body updates: 'append' (add to end), 'prepend' (add to start), or 'replace' (overwrite completely). Defaults to 'replace' if not specified.", "enum": ["append", "prepend", "replace"] }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added when updating the pull request body. When false, the visible footer content is omitted but XML markers are still included. Defaults to true. Only applies when 'body' is enabled.", "default": true }, "max": { "description": "Maximum number of pull requests to update (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository pull request updates. Takes precedence over trial target repo settings." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable pull request updating with default configuration (title and body updates enabled)" } ], "description": "Enable AI agents to edit and update existing pull request content, titles, labels, reviewers, and metadata." }, "push-to-pull-request-branch": { "oneOf": [ { "type": "null", "description": "Use default configuration (branch: 'triggering', if-no-changes: 'warn')" }, { "type": "object", "description": "Configuration for pushing changes to a specific branch from agentic workflow output. Supports pushing to multiple PRs in a single run when max > 1.", "properties": { "max": { "description": "Maximum number of push operations to perform (default: 1). Each push targets a different pull request branch. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "branch": { "type": "string", "description": "The branch to push changes to (defaults to 'triggering')" }, "target": { "type": "string", "description": "Target for push operations: 'triggering' (default), '*' (any pull request), or explicit pull request number" }, "title-prefix": { "type": "string", "description": "Required prefix for pull request title. Only pull requests with this prefix will be accepted." }, "labels": { "type": "array", "description": "Required labels for pull request validation. Only pull requests with all these labels will be accepted.", "items": { "type": "string" } }, "if-no-changes": { "type": "string", "enum": ["warn", "error", "ignore"], "description": "Behavior when no changes to push: 'warn' (default - log warning but succeed), 'error' (fail the action), or 'ignore' (silent success)" }, "commit-title-suffix": { "type": "string", "description": "Optional suffix to append to generated commit titles (e.g., ' [skip ci]' to prevent triggering CI on the commit)" }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] }, "github-token-for-extra-empty-commit": { "type": "string", "description": "Token used to push an empty commit after pushing changes to trigger CI events. Works around the GITHUB_TOKEN limitation where pushes don't trigger workflow runs. Defaults to the magic secret GH_AW_CI_TRIGGER_TOKEN if set in the repository. Use a secret expression (e.g. '${{ secrets.CI_TOKEN }}') for a custom token, or 'app' for GitHub App auth." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository push to pull request branch. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' that push to pull request branch can target. When specified, the agent can use a 'repo' field in the output to specify which repository to push to. The target repository (current or target-repo) is always implicitly allowed." }, "protected-files": { "type": "string", "enum": ["blocked", "allowed", "fallback-to-issue"], "description": "Controls protected-file protection. blocked (default): hard-block any patch that modifies package manifests (e.g. package.json, go.mod), engine instruction files (e.g. AGENTS.md, CLAUDE.md) or .github/ files. allowed: allow all changes. fallback-to-issue: create a review issue instead of pushing to the PR branch, so a human can review the changes before applying.", "default": "blocked" }, "allowed-files": { "type": "array", "items": { "type": "string" }, "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern \u2014 files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)." }, "excluded-files": { "type": "array", "items": { "type": "string" }, "description": "List of glob patterns for files to exclude from the patch. Each pattern is passed to `git format-patch` as a `:(exclude)` magic pathspec, so matching files are stripped by git at generation time and will not appear in the commit. Excluded files are also not subject to `allowed-files` or `protected-files` checks. Supports * (any characters except /) and ** (any characters including /)." } }, "additionalProperties": false } ], "description": "Enable AI agents to push commits directly to pull request branches for automated fixes or improvements." }, "hide-comment": { "oneOf": [ { "type": "null", "description": "Enable comment hiding with default configuration" }, { "type": "object", "description": "Configuration for hiding comments on GitHub issues, pull requests, or discussions from agentic workflow output", "properties": { "max": { "description": "Maximum number of comments to hide (default: 5) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository comment hiding. Takes precedence over trial target repo settings." }, "allowed-reasons": { "type": "array", "description": "List of allowed reasons for hiding comments. Default: all reasons allowed (spam, abuse, off_topic, outdated, resolved).", "items": { "type": "string", "enum": ["spam", "abuse", "off_topic", "outdated", "resolved"] } }, "discussions": { "type": "boolean", "description": "Controls whether the workflow requests discussions:write permission for hide-comment. Default: true (includes discussions:write). Set to false if your GitHub App lacks Discussions permission to prevent 422 errors during token generation." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to minimize (hide) comments on issues or pull requests based on relevance, spam detection, or moderation rules." }, "set-issue-type": { "oneOf": [ { "type": "null", "description": "Null configuration allows setting any issue type" }, { "type": "object", "description": "Configuration for setting the type of GitHub issues from agentic workflow output", "properties": { "allowed": { "type": "array", "description": "Optional list of allowed issue type names (e.g. 'Bug', 'Feature'). If omitted, any type is allowed. Empty string is always allowed to clear the type.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Optional maximum number of set-issue-type operations (default: 5). Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target": { "type": "string", "description": "Target for issue type: 'triggering' (default), '*' (any issue), or explicit issue number" }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository issue type setting. Takes precedence over trial target repo settings." }, "allowed-repos": { "type": "array", "items": { "type": "string" }, "description": "List of additional repositories in format 'owner/repo' where issue types can be set. When specified, the agent can use a 'repo' field in the output to specify which repository to target. The target repository (current or target-repo) is always implicitly allowed." }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false } ], "description": "Enable AI agents to set or clear the type of GitHub issues. Use an empty string to clear the current type." }, "dispatch-workflow": { "oneOf": [ { "type": "object", "description": "Configuration for dispatching workflow_dispatch events to other workflows. Orchestrators use this to delegate work to worker workflows.", "properties": { "workflows": { "type": "array", "description": "List of workflow names (without .md extension) to allow dispatching. Each workflow must exist in .github/workflows/.", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Maximum number of workflow dispatch operations per run (default: 1, max: 50) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for dispatching workflows. Overrides global github-token if specified." }, "target-repo": { "type": "string", "description": "Target repository in format 'owner/repo' for cross-repository workflow dispatch. When specified, the workflow will be dispatched to the target repository instead of the current one." }, "target-ref": { "type": "string", "description": "Git ref (branch, tag, or SHA) to use when dispatching the workflow. For workflow_call relay scenarios this is auto-injected by the compiler from needs.activation.outputs.target_ref. Overrides the caller's GITHUB_REF." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "required": ["workflows"], "additionalProperties": false }, { "type": "array", "description": "Shorthand array format: list of workflow names (without .md extension) to allow dispatching", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 } ], "description": "Dispatch workflow_dispatch events to other workflows. Used by orchestrators to delegate work to worker workflows with controlled maximum dispatch count." }, "call-workflow": { "oneOf": [ { "type": "object", "description": "Configuration for calling reusable workflows via workflow_call fan-out. The compiler generates conditional `uses:` jobs at compile time; the agent selects which worker to activate at runtime.", "properties": { "workflows": { "type": "array", "description": "List of workflow names (without .md extension) to allow calling. Each workflow must exist in .github/workflows/ and declare a workflow_call trigger.", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 }, "max": { "description": "Maximum number of workflow_call fan-out operations per run (default: 1, max: 50). Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token passed to called workflows. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "required": ["workflows"], "additionalProperties": false }, { "type": "array", "description": "Shorthand array format: list of workflow names (without .md extension) to allow calling", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 } ], "description": "Call reusable workflows via workflow_call fan-out. The compiler generates static conditional jobs; the agent selects which worker to activate. Use this for orchestrator/dispatcher patterns within the same repository." }, "missing-tool": { "oneOf": [ { "type": "object", "description": "Configuration for reporting missing tools from agentic workflow output", "properties": { "max": { "description": "Maximum number of missing tool reports (default: unlimited) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "create-issue": { "type": "boolean", "description": "Whether to create or update GitHub issues when tools are missing (default: true)", "default": true }, "title-prefix": { "type": "string", "description": "Prefix for issue titles when creating issues for missing tools (default: '[missing tool]')", "default": "[missing tool]" }, "labels": { "type": "array", "description": "Labels to add to created issues for missing tools", "items": { "type": "string" }, "default": [] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable missing tool reporting with default configuration" }, { "type": "boolean", "const": false, "description": "Explicitly disable missing tool reporting (false). Missing tool reporting is enabled by default when safe-outputs is configured." } ], "description": "Enable AI agents to report when required MCP tools are unavailable. Used for workflow diagnostics and tool discovery." }, "missing-data": { "oneOf": [ { "type": "object", "description": "Configuration for reporting missing data required to achieve workflow goals. Encourages AI agents to be truthful about data gaps instead of hallucinating information.", "properties": { "max": { "description": "Maximum number of missing data reports (default: unlimited) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "create-issue": { "type": "boolean", "description": "Whether to create or update GitHub issues when data is missing (default: true)", "default": true }, "title-prefix": { "type": "string", "description": "Prefix for issue titles when creating issues for missing data (default: '[missing data]')", "default": "[missing data]" }, "labels": { "type": "array", "description": "Labels to add to created issues for missing data", "items": { "type": "string" }, "default": [] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable missing data reporting with default configuration" }, { "type": "boolean", "const": false, "description": "Explicitly disable missing data reporting (false). Missing data reporting is enabled by default when safe-outputs is configured." } ], "description": "Enable AI agents to report when required data or context is missing. Used for workflow troubleshooting and data validation." }, "noop": { "oneOf": [ { "type": "object", "description": "Configuration for no-op safe output (logging only, no GitHub API calls). Always available as a fallback to ensure human-visible artifacts.", "properties": { "max": { "description": "Maximum number of noop messages (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "report-as-issue": { "type": "boolean", "description": "Controls whether noop runs are reported as issue comments (default: true). Set to false to disable posting to the no-op runs issue.", "default": true }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable noop output with default configuration (max: 1)" }, { "type": "boolean", "const": false, "description": "Explicitly disable noop output (false). Noop is enabled by default when safe-outputs is configured." } ], "description": "Enable AI agents to explicitly indicate no action is needed. Used for workflow control flow and conditional logic." }, "upload-asset": { "oneOf": [ { "type": "object", "description": "Configuration for publishing assets to an orphaned git branch", "properties": { "branch": { "type": "string", "description": "Branch name (default: 'assets/${{ github.workflow }}')", "default": "assets/${{ github.workflow }}" }, "max-size": { "type": "integer", "description": "Maximum file size in KB (default: 10240 = 10MB)", "minimum": 1, "maximum": 51200, "default": 10240 }, "allowed-exts": { "type": "array", "description": "Allowed file extensions (default: common non-executable types)", "items": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" } }, "max": { "description": "Maximum number of assets to upload (default: 10) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for this specific output type. Overrides global github-token if specified." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable asset publishing with default configuration" } ], "description": "Enable AI agents to publish files (images, charts, reports) to an orphaned git branch for persistent storage and web access." }, "update-release": { "oneOf": [ { "type": "object", "description": "Configuration for updating GitHub release descriptions", "properties": { "max": { "description": "Maximum number of releases to update (default: 1) Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "target-repo": { "type": "string", "description": "Target repository for cross-repo release updates (format: owner/repo). If not specified, updates releases in the workflow's repository.", "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$" }, "footer": { "type": "boolean", "description": "Controls whether AI-generated footer is added when updating the release body. When false, the visible footer content is omitted. Defaults to true.", "default": true }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)", "examples": [true, false] } }, "additionalProperties": false }, { "type": "null", "description": "Enable release updates with default configuration" } ], "description": "Enable AI agents to edit and update GitHub release content, including release notes, assets, and metadata." }, "staged": { "type": "boolean", "description": "If true, emit step summary messages instead of making GitHub API calls (preview mode)", "examples": [true, false] }, "env": { "type": "object", "description": "Environment variables to pass to safe output jobs", "patternProperties": { "^[A-Za-z_][A-Za-z0-9_]*$": { "type": "string", "description": "Environment variable value, typically a secret reference like ${{ secrets.TOKEN_NAME }}" } }, "additionalProperties": false }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token to use for safe output jobs. Typically a secret reference like ${{ secrets.GITHUB_TOKEN }} or ${{ secrets.CUSTOM_PAT }}", "examples": ["${{ secrets.GITHUB_TOKEN }}", "${{ secrets.CUSTOM_PAT }}", "${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}"] }, "github-app": { "$ref": "#/$defs/github_app", "description": "GitHub App credentials for minting installation access tokens. When configured, a token will be generated using the app credentials and used for all safe output operations." }, "max-patch-size": { "type": "integer", "description": "Maximum allowed size for git patches in kilobytes (KB). Defaults to 1024 KB (1 MB). If patch exceeds this size, the job will fail.", "minimum": 1, "maximum": 10240, "default": 1024 }, "threat-detection": { "oneOf": [ { "type": "boolean", "description": "Enable or disable threat detection for safe outputs (defaults to true when safe-outputs are configured)" }, { "type": "object", "description": "Threat detection configuration object", "properties": { "enabled": { "type": "boolean", "description": "Whether threat detection is enabled", "default": true }, "prompt": { "type": "string", "description": "Additional custom prompt instructions to append to threat detection analysis" }, "engine": { "description": "AI engine configuration specifically for threat detection (overrides main workflow engine). Set to false to disable AI-based threat detection. Supports same format as main engine field when not false.", "oneOf": [ { "type": "boolean", "const": false, "description": "Disable AI engine for threat detection (only run custom steps)" }, { "$ref": "#/$defs/engine_config" } ] }, "steps": { "type": "array", "description": "Array of extra job steps to run after detection", "items": { "$ref": "#/$defs/githubActionsStep" } }, "runs-on": { "type": "string", "description": "Runner specification for the detection job. Overrides agent.runs-on for the detection job only. Defaults to agent.runs-on." } }, "additionalProperties": false } ], "description": "Enable AI agents to report detected security threats, policy violations, or suspicious patterns for security review." }, "jobs": { "type": "object", "description": "Custom safe-output jobs that can be executed based on agentic workflow output. Job names containing dashes will be automatically normalized to underscores (e.g., 'send-notification' becomes 'send_notification').", "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_-]*$": { "type": "object", "description": "Custom safe-output job configuration. The job name will be normalized to use underscores instead of dashes.", "properties": { "name": { "type": "string", "description": "Display name for the job" }, "description": { "type": "string", "description": "Description of the safe-job (used in MCP tool registration)" }, "runs-on": { "description": "Runner specification for this job", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "if": { "type": "string", "description": "Conditional expression for job execution" }, "needs": { "description": "Job dependencies beyond the main job", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "env": { "type": "object", "description": "Job-specific environment variables", "patternProperties": { "^[A-Za-z_][A-Za-z0-9_]*$": { "type": "string" } }, "additionalProperties": false }, "permissions": { "$ref": "#/properties/permissions" }, "github-token": { "$ref": "#/$defs/github_token", "description": "GitHub token for this specific job" }, "output": { "type": "string", "description": "Output configuration for the safe job" }, "inputs": { "type": "object", "description": "Input parameters for the safe job (workflow_dispatch syntax) - REQUIRED: at least one input must be defined", "minProperties": 1, "maxProperties": 25, "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_-]*$": { "type": "object", "properties": { "description": { "type": "string", "description": "Input parameter description" }, "required": { "type": "boolean", "description": "Whether this input is required", "default": false }, "default": { "description": "Default value for the input. Type depends on the input type: string for string/choice/environment, boolean for boolean, number for number", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] }, "type": { "type": "string", "enum": ["string", "boolean", "choice", "number", "environment"], "description": "Input parameter type. Supports: string (default), boolean, choice (string with predefined options), number, and environment (string referencing a GitHub environment)", "default": "string" }, "options": { "type": "array", "description": "Available options for choice type inputs", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "steps": { "type": "array", "description": "Custom steps to execute in the safe job", "items": { "$ref": "#/$defs/githubActionsStep" } }, "runner": { "description": "Runner specification for this job (alias for runs-on)", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "agent-output": { "type": "string", "description": "Agent output field to use as input for this safe job (alias for output)" } }, "additionalProperties": false } }, "additionalProperties": false }, "scripts": { "type": "object", "description": "Inline JavaScript script handlers that run inside the consolidated safe-outputs job handler loop. Unlike 'jobs' (which create separate GitHub Actions jobs), scripts execute in-process alongside the built-in handlers. Users write only the body of the main function — the compiler wraps it with 'async function main(config = {}) { ... }' and 'module.exports = { main };' automatically. Script names containing dashes will be automatically normalized to underscores (e.g., 'post-slack-message' becomes 'post_slack_message').", "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_-]*$": { "type": "object", "description": "Inline script handler configuration. The script body has access to 'config' (the handler config object) and should return an async function that processes individual safe-output messages.", "properties": { "name": { "type": "string", "description": "Display name for the script handler" }, "description": { "type": "string", "description": "Description of the script handler (used in MCP tool registration)" }, "inputs": { "type": "object", "description": "Input parameters for the script handler", "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_-]*$": { "type": "object", "properties": { "description": { "type": "string", "description": "Input parameter description" }, "required": { "type": "boolean", "description": "Whether this input is required", "default": false }, "default": { "description": "Default value for the input", "oneOf": [{ "type": "string" }, { "type": "boolean" }, { "type": "number" }] }, "type": { "type": "string", "enum": ["string", "boolean", "number"], "description": "Input parameter type", "default": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "script": { "type": "string", "description": "JavaScript handler body. Write only the code that runs inside the handler for each item — the compiler generates the full outer wrapper including config input destructuring (`const { channel, message } = config;`) and the handler function (`return async function handleX(item, resolvedTemporaryIds) { ... }`). The body has access to `item` (runtime message with input values), `resolvedTemporaryIds` (map of temporary IDs), and config-destructured local variables for each declared input." } }, "required": ["script"], "additionalProperties": false } }, "additionalProperties": false }, "messages": { "type": "object", "description": "Custom message templates for safe-output footer and notification messages. Available placeholders: {workflow_name} (workflow name), {run_url} (GitHub Actions run URL), {triggering_number} (issue/PR/discussion number), {workflow_source} (owner/repo/path@ref), {workflow_source_url} (GitHub URL to source), {operation} (safe-output operation name for staged mode).", "properties": { "footer": { "type": "string", "description": "Custom footer message template for AI-generated content. Available placeholders: {workflow_name}, {run_url}, {triggering_number}, {workflow_source}, {workflow_source_url}. Example: '> Generated by [{workflow_name}]({run_url})'", "examples": ["> Generated by [{workflow_name}]({run_url})", "> AI output from [{workflow_name}]({run_url}) for #{triggering_number}"] }, "footer-install": { "type": "string", "description": "Custom installation instructions template appended to the footer. Available placeholders: {workflow_source}, {workflow_source_url}. Example: '> Install: `gh aw add {workflow_source}`'", "examples": ["> Install: `gh aw add {workflow_source}`", "> [Add this workflow]({workflow_source_url})"] }, "footer-workflow-recompile": { "type": "string", "description": "Custom footer message template for workflow recompile issues. Available placeholders: {workflow_name}, {run_url}, {repository}. Example: '> Workflow sync report by [{workflow_name}]({run_url}) for {repository}'", "examples": ["> Workflow sync report by [{workflow_name}]({run_url}) for {repository}", "> Maintenance report by [{workflow_name}]({run_url})"] }, "footer-workflow-recompile-comment": { "type": "string", "description": "Custom footer message template for comments on workflow recompile issues. Available placeholders: {workflow_name}, {run_url}, {repository}. Example: '> Update from [{workflow_name}]({run_url}) for {repository}'", "examples": ["> Update from [{workflow_name}]({run_url}) for {repository}", "> Maintenance update by [{workflow_name}]({run_url})"] }, "staged-title": { "type": "string", "description": "Custom title template for staged mode preview. Available placeholders: {operation}. Example: '\ud83c\udfad Preview: {operation}'", "examples": ["\ud83c\udfad Preview: {operation}", "## Staged Mode: {operation}"] }, "staged-description": { "type": "string", "description": "Custom description template for staged mode preview. Available placeholders: {operation}. Example: 'The following {operation} would occur if staged mode was disabled:'", "examples": ["The following {operation} would occur if staged mode was disabled:"] }, "run-started": { "type": "string", "description": "Custom message template for workflow activation comment. Available placeholders: {workflow_name}, {run_url}, {event_type}. Default: 'Agentic [{workflow_name}]({run_url}) triggered by this {event_type}.'", "examples": ["Agentic [{workflow_name}]({run_url}) triggered by this {event_type}.", "[{workflow_name}]({run_url}) started processing this {event_type}."] }, "run-success": { "type": "string", "description": "Custom message template for successful workflow completion. Available placeholders: {workflow_name}, {run_url}. Default: '\u2705 Agentic [{workflow_name}]({run_url}) completed successfully.'", "examples": ["\u2705 Agentic [{workflow_name}]({run_url}) completed successfully.", "\u2705 [{workflow_name}]({run_url}) finished."] }, "run-failure": { "type": "string", "description": "Custom message template for failed workflow. Available placeholders: {workflow_name}, {run_url}, {status}. Default: '\u274c Agentic [{workflow_name}]({run_url}) {status} and wasn't able to produce a result.'", "examples": ["\u274c Agentic [{workflow_name}]({run_url}) {status} and wasn't able to produce a result.", "\u274c [{workflow_name}]({run_url}) {status}."] }, "detection-failure": { "type": "string", "description": "Custom message template for detection job failure. Available placeholders: {workflow_name}, {run_url}. Default: '\u26a0\ufe0f Security scanning failed for [{workflow_name}]({run_url}). Review the logs for details.'", "examples": ["\u26a0\ufe0f Security scanning failed for [{workflow_name}]({run_url}). Review the logs for details.", "\u26a0\ufe0f Detection job failed in [{workflow_name}]({run_url})."] }, "agent-failure-issue": { "type": "string", "description": "Custom footer template for agent failure tracking issues. Available placeholders: {workflow_name}, {run_url}. Default: '> Agent failure tracked by [{workflow_name}]({run_url})'", "examples": ["> Agent failure tracked by [{workflow_name}]({run_url})", "> Failure report from [{workflow_name}]({run_url})"] }, "agent-failure-comment": { "type": "string", "description": "Custom footer template for comments on agent failure tracking issues. Available placeholders: {workflow_name}, {run_url}. Default: '> Agent failure update from [{workflow_name}]({run_url})'", "examples": ["> Agent failure update from [{workflow_name}]({run_url})", "> Update from [{workflow_name}]({run_url})"] }, "pull-request-created": { "type": "string", "description": "Custom message template for pull request creation link appended to the activation comment. Available placeholders: {item_number}, {item_url}. Default: 'Pull request created: [#{item_number}]({item_url})'", "examples": ["Pull request created: [#{item_number}]({item_url})", "[#{item_number}]({item_url}) opened"] }, "issue-created": { "type": "string", "description": "Custom message template for issue creation link appended to the activation comment. Available placeholders: {item_number}, {item_url}. Default: 'Issue created: [#{item_number}]({item_url})'", "examples": ["Issue created: [#{item_number}]({item_url})", "[#{item_number}]({item_url}) filed"] }, "commit-pushed": { "type": "string", "description": "Custom message template for commit push link appended to the activation comment. Available placeholders: {commit_sha}, {short_sha}, {commit_url}. Default: 'Commit pushed: [`{short_sha}`]({commit_url})'", "examples": ["Commit pushed: [`{short_sha}`]({commit_url})", "[`{short_sha}`]({commit_url}) pushed"] }, "append-only-comments": { "type": "boolean", "description": "When enabled, workflow completion notifier creates a new comment instead of editing the activation comment. Creates an append-only timeline of workflow runs. Default: false", "default": false } }, "additionalProperties": false }, "mentions": { "description": "Configuration for @mention filtering in safe outputs. Controls whether and how @mentions in AI-generated content are allowed or escaped.", "oneOf": [ { "type": "boolean", "description": "Simple boolean mode: false = always escape mentions, true = always allow mentions (error in strict mode)" }, { "type": "object", "description": "Advanced configuration for @mention filtering with fine-grained control", "properties": { "allow-team-members": { "type": "boolean", "description": "Allow mentions of repository team members (collaborators with any permission level, excluding bots). Default: true", "default": true }, "allow-context": { "type": "boolean", "description": "Allow mentions inferred from event context (issue/PR authors, assignees, commenters). Default: true", "default": true }, "allowed": { "type": "array", "description": "List of user/bot names always allowed to be mentioned. Bots are not allowed by default unless listed here.", "items": { "type": "string", "minLength": 1 } }, "max": { "description": "Maximum number of mentions allowed per message. Default: 50 Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "default": 50 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] } }, "additionalProperties": false } ] }, "footer": { "type": "boolean", "description": "Global footer control for all safe outputs. When false, omits visible AI-generated footer content from all created/updated entities (issues, PRs, discussions, releases) while still including XML markers for searchability. Individual safe-output types (create-issue, update-issue, etc.) can override this by specifying their own footer field. Defaults to true.", "default": true, "examples": [false, true] }, "activation-comments": { "type": ["boolean", "string"], "description": "When set to false or \"false\", disables all activation and fallback comments entirely (run-started, run-success, run-failure, PR/issue creation links). Supports templatable boolean values including GitHub Actions expressions (e.g. ${{ inputs.activation-comments }}). Default: true", "default": true, "examples": [false, true, "${{ inputs.activation-comments }}"] }, "group-reports": { "type": "boolean", "description": "When true, creates a parent '[aw] Failed runs' issue that tracks all workflow failures as sub-issues. Helps organize failure tracking but may be unnecessary in smaller repositories. Defaults to false.", "default": false, "examples": [false, true] }, "report-failure-as-issue": { "type": "boolean", "description": "When false, disables creating failure tracking issues when workflows fail. Useful for workflows where failures are expected or handled elsewhere. Defaults to true.", "default": true, "examples": [false, true] }, "failure-issue-repo": { "type": "string", "description": "Repository to create failure tracking issues in, in the format 'owner/repo'. Useful when the current repository has issues disabled. Defaults to the current repository.", "pattern": "^[^/]+/[^/]+$", "examples": ["github/docs-engineering", "myorg/infra-alerts"] }, "max-bot-mentions": { "description": "Maximum number of bot trigger references (e.g. 'fixes #123', 'closes #456') allowed in output before all of them are neutralized. Default: 10. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max-bot-mentions }}').", "oneOf": [ { "type": "integer", "minimum": 1, "default": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "id-token": { "type": "string", "enum": ["write", "none"], "description": "Override the id-token permission for the safe-outputs job. Use 'write' to force-enable the id-token: write permission (required for OIDC authentication with cloud providers). Use 'none' to suppress automatic detection and prevent adding id-token: write even when vault/OIDC actions are detected in steps. By default, the compiler auto-detects known OIDC/vault actions (aws-actions/configure-aws-credentials, azure/login, google-github-actions/auth, hashicorp/vault-action, cyberark/conjur-action) and adds id-token: write automatically.", "examples": ["write", "none"] }, "concurrency-group": { "type": "string", "description": "Concurrency group for the safe-outputs job. When set, the safe-outputs job will use this concurrency group with cancel-in-progress: false. Supports GitHub Actions expressions.", "examples": ["my-workflow-safe-outputs", "safe-outputs-${{ github.repository }}"] }, "environment": { "description": "Override the GitHub deployment environment for the safe-outputs job. When set, this environment is used instead of the top-level environment: field. When not set, the top-level environment: field is propagated automatically so that environment-scoped secrets are accessible in the safe-outputs job.", "oneOf": [ { "type": "string", "description": "Environment name as a string" }, { "type": "object", "description": "Environment object with name and optional URL", "properties": { "name": { "type": "string", "description": "The name of the environment configured in the repo" }, "url": { "type": "string", "description": "A deployment URL" } }, "required": ["name"], "additionalProperties": false } ] }, "runs-on": { "type": "string", "description": "Runner specification for all safe-outputs jobs (activation, create-issue, add-comment, etc.). Single runner label (e.g., 'ubuntu-slim', 'ubuntu-latest', 'windows-latest', 'self-hosted'). Defaults to 'ubuntu-slim'. See https://github.blog/changelog/2025-10-28-1-vcpu-linux-runner-now-available-in-github-actions-in-public-preview/" }, "steps": { "type": "array", "description": "Custom steps to inject into all safe-output jobs. These steps run after checking out the repository and setting up the action, and before any safe-output code executes.", "items": { "$ref": "#/$defs/githubActionsStep" }, "examples": [ [ { "name": "Install custom dependencies", "run": "npm install my-package" } ] ] }, "actions": { "type": "object", "description": "Custom GitHub Actions to mount as once-callable MCP tools. Each action is resolved at compile time to derive its input schema from action.yml, and a guarded `uses:` step is injected in the safe_outputs job. Action names containing dashes will be automatically normalized to underscores (e.g., 'add-smoked-label' becomes 'add_smoked_label').", "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_-]*$": { "type": "object", "description": "Configuration for a custom safe output action.", "properties": { "uses": { "type": "string", "description": "The GitHub Action to use. Supports owner/repo@ref, owner/repo/subdir@ref, or ./local/path.", "examples": ["actions-ecosystem/action-add-labels@v1", "owner/repo@v1", "owner/repo/subdir@v1"] }, "description": { "type": "string", "description": "Optional description override for the MCP tool. Defaults to the action's description from action.yml." }, "env": { "type": "object", "description": "Additional environment variables to set on the injected action step. Useful for passing secrets like GITHUB_TOKEN.", "additionalProperties": { "type": "string" }, "examples": [{ "GITHUB_TOKEN": "${{ github.token }}" }] } }, "required": ["uses"], "additionalProperties": false } } } }, "additionalProperties": false }, "secret-masking": { "type": "object", "description": "Configuration for secret redaction behavior in workflow outputs and artifacts", "properties": { "steps": { "type": "array", "description": "Additional secret redaction steps to inject after the built-in secret redaction. Use this to mask secrets in generated files using custom patterns.", "items": { "$ref": "#/$defs/githubActionsStep" }, "examples": [ [ { "name": "Redact custom secrets", "run": "find /tmp/gh-aw -type f -exec sed -i 's/password123/REDACTED/g' {} +" } ] ] } }, "additionalProperties": false }, "bots": { "type": "array", "description": "Allow list of bot identifiers that can trigger the workflow even if they don't meet the required role permissions. When the actor is in this list, the bot must be active (installed) on the repository to trigger the workflow.", "items": { "type": "string", "minLength": 1, "description": "Bot identifier/name (e.g., 'dependabot[bot]', 'renovate[bot]', 'github-actions[bot]')" } }, "rate-limit": { "type": "object", "description": "Rate limiting configuration to restrict how frequently users can trigger the workflow. Helps prevent abuse and resource exhaustion from programmatically triggered events.", "required": ["max"], "properties": { "max": { "description": "Maximum number of workflow runs allowed per user within the time window. Required field. Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}').", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "window": { "type": "integer", "minimum": 1, "maximum": 180, "default": 60, "description": "Time window in minutes for rate limiting. Defaults to 60 (1 hour). Maximum: 180 (3 hours)." }, "events": { "type": "array", "description": "Optional list of event types to apply rate limiting to. If not specified, rate limiting applies to all programmatically triggered events (e.g., workflow_dispatch, issue_comment, pull_request_review).", "items": { "type": "string", "enum": ["workflow_dispatch", "issue_comment", "pull_request_review", "pull_request_review_comment", "issues", "pull_request", "discussion_comment", "discussion"] }, "minItems": 1 }, "ignored-roles": { "type": "array", "description": "Optional list of roles that are exempt from rate limiting. Defaults to ['admin', 'maintain', 'write'] if not specified. Users with any of these roles will not be subject to rate limiting checks. To apply rate limiting to all users, set to an empty array: []", "items": { "type": "string", "enum": ["admin", "maintain", "write", "triage", "read"] }, "minItems": 0 } }, "additionalProperties": false, "examples": [ { "max": 5, "window": 60 }, { "max": 10, "window": 30, "events": ["workflow_dispatch", "issue_comment"] }, { "max": 5, "window": 60, "ignored-roles": ["admin", "maintain"] } ] }, "strict": { "type": "boolean", "default": true, "$comment": "Strict mode enforces several security constraints that are validated in Go code (pkg/workflow/strict_mode_validation.go) rather than JSON Schema: (1) Write Permissions + Safe Outputs: When strict=true AND permissions contains write values (contents:write, issues:write, pull-requests:write), safe-outputs must be configured. This relationship is too complex for JSON Schema as it requires checking if ANY permission property has a 'write' value. (2) Network Requirements: When strict=true, the 'network' field must be present and cannot contain standalone wildcard '*' (but patterns like '*.example.com' ARE allowed). (3) MCP Container Network: Custom MCP servers with containers require explicit network configuration. (4) Action Pinning: Actions must be pinned to commit SHAs. These are enforced during compilation via validateStrictMode().", "description": "Enable strict mode validation for enhanced security and compliance. Strict mode enforces: (1) Write Permissions - refuses contents:write, issues:write, pull-requests:write; requires safe-outputs instead, (2) Network Configuration - requires explicit network configuration with no standalone wildcard '*' in allowed domains (patterns like '*.example.com' are allowed), (3) Action Pinning - enforces actions pinned to commit SHAs instead of tags/branches, (4) MCP Network - requires network configuration for custom MCP servers with containers, (5) Deprecated Fields - refuses deprecated frontmatter fields. Can be enabled per-workflow via 'strict: true' in frontmatter, or disabled via 'strict: false'. CLI flag takes precedence over frontmatter (gh aw compile --strict enforces strict mode). Defaults to true. See: https://github.github.com/gh-aw/reference/frontmatter/#strict-mode-strict", "examples": [true, false] }, "private": { "type": "boolean", "default": false, "description": "Mark the workflow as private, preventing it from being added to other repositories via 'gh aw add'. A workflow with private: true is not meant to be shared outside its repository.", "examples": [true, false] }, "mcp-scripts": { "type": "object", "description": "MCP Scripts configuration for defining custom lightweight MCP tools as JavaScript, shell scripts, or Python scripts. Tools are mounted in an MCP server and have access to secrets specified by the user. Only one of 'script' (JavaScript), 'run' (shell), or 'py' (Python) must be specified per tool.", "patternProperties": { "^([a-ln-z][a-z0-9_-]*|m[a-np-z][a-z0-9_-]*|mo[a-ce-z][a-z0-9_-]*|mod[a-df-z][a-z0-9_-]*|mode[a-z0-9_-]+)$": { "type": "object", "description": "Custom tool definition. The key is the tool name (lowercase alphanumeric with dashes/underscores).", "required": ["description"], "properties": { "description": { "type": "string", "description": "Tool description that explains what the tool does. This is required and will be shown to the AI agent." }, "inputs": { "type": "object", "description": "Optional input parameters for the tool using workflow syntax. Each property defines an input with its type and description.", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": ["string", "number", "boolean", "array", "object"], "default": "string", "description": "The JSON schema type of the input parameter." }, "description": { "type": "string", "description": "Description of the input parameter." }, "required": { "type": "boolean", "default": false, "description": "Whether this input is required." }, "default": { "description": "Default value for the input parameter." } }, "additionalProperties": false } }, "script": { "type": "string", "description": "JavaScript implementation (CommonJS format). The script receives input parameters as a JSON object and should return a result. Cannot be used together with 'run', 'py', or 'go'." }, "run": { "type": "string", "description": "Shell script implementation. The script receives input parameters as environment variables (JSON-encoded for complex types). Cannot be used together with 'script', 'py', or 'go'." }, "py": { "type": "string", "description": "Python script implementation. The script receives input parameters as environment variables (INPUT_* prefix, uppercased). Cannot be used together with 'script', 'run', or 'go'." }, "go": { "type": "string", "description": "Go script implementation. The script is executed using 'go run' and receives input parameters as JSON via stdin. Cannot be used together with 'script', 'run', or 'py'." }, "env": { "type": "object", "description": "Environment variables to pass to the tool, typically for secrets. Use ${{ secrets.NAME }} syntax.", "additionalProperties": { "type": "string" }, "examples": [ { "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}", "API_KEY": "${{ secrets.MY_API_KEY }}" } ] }, "timeout": { "type": "integer", "description": "Timeout in seconds for tool execution. Default is 60 seconds. Applies to shell (run) and Python (py) tools.", "default": 60, "minimum": 1, "examples": [30, 60, 120, 300] } }, "additionalProperties": false, "oneOf": [ { "required": ["script"], "not": { "anyOf": [ { "required": ["run"] }, { "required": ["py"] }, { "required": ["go"] } ] } }, { "required": ["run"], "not": { "anyOf": [ { "required": ["script"] }, { "required": ["py"] }, { "required": ["go"] } ] } }, { "required": ["py"], "not": { "anyOf": [ { "required": ["script"] }, { "required": ["run"] }, { "required": ["go"] } ] } }, { "required": ["go"], "not": { "anyOf": [ { "required": ["script"] }, { "required": ["run"] }, { "required": ["py"] } ] } } ] } }, "examples": [ { "search-issues": { "description": "Search GitHub issues using the GitHub API", "inputs": { "query": { "type": "string", "description": "Search query for issues", "required": true }, "limit": { "type": "number", "description": "Maximum number of results", "default": 10 } }, "script": "const { Octokit } = require('@octokit/rest');\nconst octokit = new Octokit({ auth: process.env.GH_TOKEN });\nconst result = await octokit.search.issuesAndPullRequests({ q: inputs.query, per_page: inputs.limit });\nreturn result.data.items;", "env": { "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}" } } }, { "run-linter": { "description": "Run a custom linter on the codebase", "inputs": { "path": { "type": "string", "description": "Path to lint", "default": "." } }, "run": "eslint $INPUT_PATH --format json", "env": { "INPUT_PATH": "${{ inputs.path }}" } } } ], "additionalProperties": false }, "runtimes": { "type": "object", "description": "Runtime environment version overrides. Allows customizing runtime versions (e.g., Node.js, Python) or defining new runtimes. Runtimes from imported shared workflows are also merged.", "patternProperties": { "^[a-z][a-z0-9-]*$": { "type": "object", "description": "Runtime configuration object identified by runtime ID (e.g., 'node', 'python', 'go')", "properties": { "version": { "type": ["string", "number"], "description": "Runtime version as a string (e.g., '22', '3.12', 'latest') or number (e.g., 22, 3.12). Numeric values are automatically converted to strings at runtime.", "examples": ["22", "3.12", "latest", 22, 3.12] }, "action-repo": { "type": "string", "description": "GitHub Actions repository for setting up the runtime (e.g., 'actions/setup-node', 'custom/setup-runtime'). Overrides the default setup action." }, "action-version": { "type": "string", "description": "Version of the setup action to use (e.g., 'v4', 'v5'). Overrides the default action version." }, "if": { "type": "string", "description": "Optional GitHub Actions if condition to control when the runtime setup step runs. Supports standard GitHub Actions expression syntax. Useful for conditionally installing runtimes based on file presence (e.g., \"hashFiles('go.mod') != ''\" to install Go only when go.mod exists).", "examples": ["hashFiles('go.mod') != ''", "hashFiles('package.json') != ''", "hashFiles('requirements.txt') != '' || hashFiles('pyproject.toml') != ''", "hashFiles('uv.lock') != ''", "github.event_name == 'workflow_dispatch'"] } }, "additionalProperties": false } }, "additionalProperties": false }, "checkout": { "description": "Checkout configuration for the agent job. Controls how actions/checkout is invoked. Can be a single checkout configuration, an array for multiple checkouts, or false to disable the default checkout step entirely (dev-mode checkouts are unaffected).", "oneOf": [ { "$ref": "#/$defs/checkoutConfig", "description": "Single checkout configuration for the default workspace" }, { "type": "array", "description": "Multiple checkout configurations", "items": { "$ref": "#/$defs/checkoutConfig" } }, { "type": "boolean", "enum": [false], "description": "Set to false to disable the default checkout step. The agent job will not check out any repository (dev-mode checkouts are unaffected)." } ] }, "dependencies": { "description": "APM package references to install. Supports array format (list of package slugs) or object format with packages and isolated fields.", "examples": [ ["microsoft/apm-sample-package", "acme/custom-tools"], { "packages": ["microsoft/apm-sample-package"], "isolated": true } ], "oneOf": [ { "type": "array", "description": "Simple array of APM package references.", "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$", "description": "APM package reference in the format 'org/repo' or 'org/repo/path/to/skill'" } }, { "type": "object", "description": "Object format with packages and optional isolated flag.", "properties": { "packages": { "type": "array", "description": "List of APM package references to install.", "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$", "description": "APM package reference in the format 'org/repo' or 'org/repo/path/to/skill'" } }, "isolated": { "type": "boolean", "description": "If true, agent restore step clears primitive dirs before unpacking." }, "github-app": { "$ref": "#/$defs/github_app", "description": "GitHub App credentials for minting installation access tokens used by APM to access cross-org private repositories." }, "env": { "type": "object", "description": "Environment variables to set on the APM pack step (e.g., tokens or registry URLs).", "additionalProperties": { "type": "string" } } }, "required": ["packages"], "additionalProperties": false } ] }, "github-app": { "$ref": "#/$defs/github_app", "description": "Top-level GitHub App configuration used as a fallback for all nested github-app token minting operations (on, safe-outputs, checkout, tools.github, dependencies). When a nested section does not define its own github-app, this top-level configuration is used automatically." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "on": { "type": "object", "anyOf": [ { "properties": { "slash_command": { "not": { "type": "null" } } }, "required": ["slash_command"] }, { "properties": { "command": { "not": { "type": "null" } } }, "required": ["command"] } ] } } }, "then": { "properties": { "on": { "not": { "anyOf": [ { "properties": { "issue_comment": { "not": { "type": "null" } } }, "required": ["issue_comment"] }, { "properties": { "pull_request_review_comment": { "not": { "type": "null" } } }, "required": ["pull_request_review_comment"] }, { "properties": { "label": { "not": { "type": "null" } } }, "required": ["label"] } ] } } } } } ], "$defs": { "templatable_boolean": { "description": "A boolean value that may also be specified as a GitHub Actions expression string that resolves to a boolean at runtime (e.g. '${{ inputs.my-flag }}').", "oneOf": [ { "type": "boolean" }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to a boolean at runtime" } ] }, "templatable_integer": { "description": "A non-negative integer value that may also be specified as a GitHub Actions expression string that resolves to an integer at runtime (e.g. '${{ inputs.max-issues }}').", "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\$\\{\\{.*\\}\\}$", "description": "GitHub Actions expression that resolves to an integer at runtime" } ] }, "job_strategy": { "type": "object", "description": "Matrix strategy for the job. Defines multiple job configurations using matrix variables.", "properties": { "matrix": { "type": "object", "description": "Matrix variables for creating job variants. Each key defines a dimension of the matrix, with values as arrays (e.g., {os: [ubuntu-latest, windows-latest]}). Use 'include' to add extra configurations and 'exclude' to remove specific combinations.", "additionalProperties": true }, "fail-fast": { "type": "boolean", "description": "If true, GitHub cancels all in-progress jobs if any matrix job fails. Defaults to true." }, "max-parallel": { "type": "integer", "minimum": 1, "description": "Maximum number of jobs to run simultaneously when using a matrix strategy." } }, "additionalProperties": false }, "engine_config": { "examples": [ "claude", "copilot", { "id": "claude", "model": "claude-3-5-sonnet-20241022", "max-turns": 15 }, { "id": "copilot", "version": "beta" }, { "id": "copilot", "max-continuations": 5 }, { "id": "claude", "concurrency": { "group": "gh-aw-claude", "cancel-in-progress": false } }, { "runtime": { "id": "codex", "version": "0.105.0" }, "provider": { "id": "openai", "model": "gpt-5", "auth": { "secret": "OPENAI_API_KEY" } } }, { "runtime": { "id": "claude" }, "provider": { "model": "claude-3-7-sonnet-20250219" } }, { "runtime": { "id": "codex" }, "provider": { "id": "azure-openai", "model": "gpt-4o", "auth": { "strategy": "oauth-client-credentials", "token-url": "https://auth.example.com/oauth/token", "client-id": "AZURE_CLIENT_ID", "client-secret": "AZURE_CLIENT_SECRET", "header-name": "api-key" }, "request": { "path-template": "/openai/deployments/{model}/chat/completions", "query": { "api-version": "2024-10-01-preview" } } } } ], "oneOf": [ { "type": "string", "description": "Engine name: built-in ('claude', 'codex', 'copilot', 'gemini') or a named catalog entry" }, { "type": "object", "description": "Extended engine configuration object with advanced options for model selection, turn limiting, environment variables, and custom steps", "properties": { "id": { "type": "string", "description": "AI engine identifier: built-in ('claude', 'codex', 'copilot', 'gemini') or a named catalog entry" }, "version": { "type": ["string", "number"], "description": "Optional version of the AI engine action (e.g., 'beta', 'stable', 20). Has sensible defaults and can typically be omitted. Numeric values are automatically converted to strings at runtime.", "examples": ["beta", "stable", 20, 3.11] }, "model": { "type": "string", "description": "Optional specific LLM model to use (e.g., 'claude-3-5-sonnet-20241022', 'gpt-4'). Has sensible defaults and can typically be omitted." }, "max-turns": { "oneOf": [ { "type": "integer", "description": "Maximum number of chat iterations per run as an integer value" }, { "type": "string", "description": "Maximum number of chat iterations per run as a string value" } ], "description": "Maximum number of chat iterations per run. Helps prevent runaway loops and control costs. Has sensible defaults and can typically be omitted. Note: Only supported by the claude engine." }, "max-continuations": { "type": "integer", "minimum": 1, "description": "Maximum number of continuations for multi-run autopilot mode. Default is 1 (single run, no autopilot). Values greater than 1 enable --autopilot mode for the copilot engine with --max-autopilot-continues set to this value. Note: Only supported by the copilot engine." }, "concurrency": { "oneOf": [ { "type": "string", "description": "Simple concurrency group name. Gets converted to GitHub Actions concurrency format with the specified group." }, { "type": "object", "description": "GitHub Actions concurrency configuration for the agent job. Controls how many agentic workflow runs can run concurrently.", "properties": { "group": { "type": "string", "description": "Concurrency group identifier. Use GitHub Actions expressions like ${{ github.workflow }} or ${{ github.ref }}. Defaults to 'gh-aw-{engine-id}' if not specified." }, "cancel-in-progress": { "type": "boolean", "description": "Whether to cancel in-progress runs of the same concurrency group. Defaults to false for agentic workflow runs." } }, "required": ["group"], "additionalProperties": false } ], "description": "Agent job concurrency configuration. Defaults to single job per engine across all workflows (group: 'gh-aw-{engine-id}'). Supports full GitHub Actions concurrency syntax." }, "user-agent": { "type": "string", "description": "Custom user agent string for GitHub MCP server configuration (codex engine only)" }, "command": { "type": "string", "description": "Custom executable path for the AI engine CLI. When specified, the workflow will skip the standard installation steps and use this command instead. The command should be the full path to the executable or a command available in PATH." }, "env": { "type": "object", "description": "Custom environment variables to pass to the AI engine, including secret overrides (e.g., OPENAI_API_KEY: ${{ secrets.CUSTOM_KEY }})", "additionalProperties": { "type": "string" } }, "error_patterns": { "type": "array", "description": "Custom error patterns for validating agent logs", "items": { "type": "object", "description": "Error pattern definition", "properties": { "id": { "type": "string", "description": "Unique identifier for this error pattern" }, "pattern": { "type": "string", "description": "Ecma script regular expression pattern to match log lines" }, "level_group": { "type": "integer", "minimum": 0, "description": "Capture group index (1-based) that contains the error level. Use 0 to infer from pattern content." }, "message_group": { "type": "integer", "minimum": 0, "description": "Capture group index (1-based) that contains the error message. Use 0 to use the entire match." }, "description": { "type": "string", "description": "Human-readable description of what this pattern matches" } }, "required": ["pattern"], "additionalProperties": false } }, "config": { "type": "string", "description": "Additional TOML configuration text that will be appended to the generated config.toml in the action (codex engine only)" }, "agent": { "type": "string", "description": "Agent identifier to pass to copilot --agent flag (copilot engine only). Specifies which custom agent to use for the workflow." }, "api-target": { "type": "string", "description": "Custom API endpoint hostname for the agentic engine. Used for GitHub Enterprise Cloud (GHEC), GitHub Enterprise Server (GHES), or custom AI endpoints. Example: 'api.acme.ghe.com' for GHEC, 'api.enterprise.githubcopilot.com' for GHES, or custom endpoint hostnames.", "examples": ["api.acme.ghe.com", "api.enterprise.githubcopilot.com", "api.custom.endpoint.com"] }, "args": { "type": "array", "items": { "type": "string" }, "description": "Optional array of command-line arguments to pass to the AI engine CLI. These arguments are injected after all other args but before the prompt." } }, "required": ["id"], "additionalProperties": false }, { "type": "object", "description": "Inline engine definition: specifies a runtime adapter and optional provider settings directly in the workflow frontmatter, without requiring a named catalog entry", "properties": { "runtime": { "type": "object", "description": "Runtime adapter reference for the inline engine definition", "properties": { "id": { "type": "string", "description": "Runtime adapter identifier (e.g. 'codex', 'claude', 'copilot', 'gemini')", "examples": ["codex", "claude", "copilot", "gemini"] }, "version": { "type": ["string", "number"], "description": "Optional version of the runtime adapter (e.g. '0.105.0', 'beta')", "examples": ["0.105.0", "beta", "latest"] } }, "required": ["id"], "additionalProperties": false }, "provider": { "type": "object", "description": "Optional provider configuration for the inline engine definition", "properties": { "id": { "type": "string", "description": "Provider identifier (e.g. 'openai', 'anthropic', 'github', 'google')", "examples": ["openai", "anthropic", "github", "google"] }, "model": { "type": "string", "description": "Optional specific LLM model to use (e.g. 'gpt-5', 'claude-3-5-sonnet-20241022')", "examples": ["gpt-5", "claude-3-5-sonnet-20241022", "gpt-4o"] }, "auth": { "type": "object", "description": "Authentication configuration for the provider", "properties": { "secret": { "type": "string", "description": "Name of the GitHub Actions secret that contains the API key for this provider", "examples": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "CUSTOM_API_KEY"] }, "strategy": { "type": "string", "enum": ["api-key", "oauth-client-credentials", "bearer"], "description": "Authentication strategy for the provider (default: api-key when secret is set)" }, "token-url": { "type": "string", "description": "OAuth 2.0 token endpoint URL. Required when strategy is 'oauth-client-credentials'.", "examples": ["https://auth.example.com/oauth/token"] }, "client-id": { "type": "string", "description": "GitHub Actions secret name that holds the OAuth client ID. Required when strategy is 'oauth-client-credentials'.", "examples": ["OAUTH_CLIENT_ID"] }, "client-secret": { "type": "string", "description": "GitHub Actions secret name that holds the OAuth client secret. Required when strategy is 'oauth-client-credentials'.", "examples": ["OAUTH_CLIENT_SECRET"] }, "token-field": { "type": "string", "description": "JSON field name in the token response that contains the access token. Defaults to 'access_token'.", "examples": ["access_token", "token"] }, "header-name": { "type": "string", "description": "HTTP header name to inject the API key or token into (e.g. 'api-key', 'x-api-key'). Required when strategy is not 'bearer'.", "examples": ["api-key", "x-api-key", "Authorization"] } }, "additionalProperties": false }, "request": { "type": "object", "description": "Request shaping configuration for non-standard provider URL and body transformations", "properties": { "path-template": { "type": "string", "description": "URL path template with {model} and other variable placeholders (e.g. '/openai/deployments/{model}/chat/completions')", "examples": ["/openai/deployments/{model}/chat/completions"] }, "query": { "type": "object", "description": "Static or template query-parameter values appended to every request", "additionalProperties": { "type": "string" }, "examples": [ { "api-version": "2024-10-01-preview" } ] }, "body-inject": { "type": "object", "description": "Key/value pairs injected into the JSON request body before sending", "additionalProperties": { "type": "string" }, "examples": [ { "appKey": "{APP_KEY_SECRET}" } ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": ["runtime"], "additionalProperties": false }, { "type": "object", "description": "Engine definition: full declarative metadata for a named engine entry (used in builtin engine shared workflow files such as @builtin:engines/*.md)", "properties": { "id": { "type": "string", "description": "Unique engine identifier (e.g. 'copilot', 'claude', 'codex', 'gemini')" }, "display-name": { "type": "string", "description": "Human-readable display name for the engine" }, "description": { "type": "string", "description": "Human-readable description of the engine" }, "runtime-id": { "type": "string", "description": "Runtime adapter identifier. Maps to the CodingAgentEngine registered in the engine registry. Defaults to id when omitted." }, "provider": { "type": "object", "description": "Provider metadata for the engine", "properties": { "name": { "type": "string", "description": "Provider name (e.g. 'anthropic', 'github', 'google', 'openai')" }, "auth": { "type": "object", "description": "Default authentication configuration for the provider", "properties": { "secret": { "type": "string", "description": "Name of the GitHub Actions secret that contains the API key" }, "strategy": { "type": "string", "enum": ["api-key", "oauth-client-credentials", "bearer"], "description": "Authentication strategy" }, "token-url": { "type": "string", "description": "OAuth 2.0 token endpoint URL" }, "client-id": { "type": "string", "description": "GitHub Actions secret name for the OAuth client ID" }, "client-secret": { "type": "string", "description": "GitHub Actions secret name for the OAuth client secret" }, "token-field": { "type": "string", "description": "JSON field name in the token response containing the access token" }, "header-name": { "type": "string", "description": "HTTP header name to inject the API key or token into" } }, "additionalProperties": false }, "request": { "type": "object", "description": "Request shaping configuration", "properties": { "path-template": { "type": "string", "description": "URL path template with variable placeholders" }, "query": { "type": "object", "description": "Static query parameters", "additionalProperties": { "type": "string" } }, "body-inject": { "type": "object", "description": "Key/value pairs injected into the JSON request body", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "models": { "type": "object", "description": "Model selection configuration for the engine", "properties": { "default": { "type": "string", "description": "Default model identifier" }, "supported": { "type": "array", "items": { "type": "string" }, "description": "List of supported model identifiers" } }, "additionalProperties": false }, "auth": { "type": "array", "description": "Authentication bindings \u2014 maps logical roles (e.g. 'api-key') to GitHub Actions secret names", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "Logical authentication role (e.g. 'api-key', 'token')" }, "secret": { "type": "string", "description": "Name of the GitHub Actions secret that provides credentials for this role" } }, "required": ["role", "secret"], "additionalProperties": false } }, "options": { "type": "object", "description": "Additional engine-specific options", "additionalProperties": true } }, "required": ["id", "display-name"], "additionalProperties": false } ] }, "stdio_mcp_tool": { "type": "object", "description": "Stdio MCP tool configuration", "properties": { "type": { "type": "string", "enum": ["stdio", "local"], "description": "MCP connection type for stdio (local is an alias for stdio)" }, "registry": { "type": "string", "description": "URI to the installation location when MCP is installed from a registry", "examples": ["https://api.mcp.github.com/v0/servers/microsoft/markitdown"] }, "command": { "type": "string", "minLength": 1, "$comment": "Mutually exclusive with 'container' - only one execution mode can be specified. Validated by 'not.allOf' constraint below.", "description": "Command for stdio MCP connections" }, "container": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$", "$comment": "Mutually exclusive with 'command' - only one execution mode can be specified. Validated by 'not.allOf' constraint below.", "description": "Container image for stdio MCP connections" }, "version": { "type": ["string", "number"], "description": "Optional version/tag for the container image (e.g., 'latest', 'v1.0.0', 20, 3.11). Numeric values are automatically converted to strings at runtime.", "examples": ["latest", "v1.0.0", 20, 3.11] }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments for command or container execution" }, "entrypoint": { "type": "string", "description": "Optional entrypoint override for container (equivalent to docker run --entrypoint)", "examples": ["/bin/sh", "/custom/entrypoint.sh", "python"] }, "entrypointArgs": { "type": "array", "items": { "type": "string" }, "description": "Arguments to add after the container image (container entrypoint arguments)" }, "mounts": { "type": "array", "items": { "type": "string", "pattern": "^[^:]+:[^:]+:(ro|rw)$" }, "description": "Volume mounts for container in format 'source:dest:mode' where mode is 'ro' or 'rw'", "examples": [["/tmp/data:/data:ro"], ["/workspace:/workspace:rw", "/config:/config:ro"]] }, "env": { "type": "object", "patternProperties": { "^[A-Z_][A-Z0-9_]*$": { "type": "string" } }, "additionalProperties": false, "description": "Environment variables for MCP server" }, "network": { "type": "object", "deprecated": true, "$comment": "DEPRECATED: Per-server network configuration is no longer supported. Use top-level workflow 'network:' configuration instead.", "properties": { "allowed": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?)*$", "description": "Allowed domain name" }, "minItems": 1, "uniqueItems": true, "description": "List of allowed domain names for network access", "maxItems": 100 }, "proxy-args": { "type": "array", "items": { "type": "string" }, "description": "Custom proxy arguments for container-based MCP servers" } }, "additionalProperties": false, "description": "DEPRECATED: Per-server network configuration is no longer supported. Use top-level workflow 'network:' configuration instead. This field is ignored and will be removed in a future version." }, "allowed": { "type": "array", "description": "List of allowed tool names for this MCP server", "items": { "type": "string" }, "examples": [["*"], ["store_memory", "retrieve_memory"], ["brave_web_search"]] } }, "additionalProperties": false, "$comment": "Validation constraints: (1) Mutual exclusion: 'command' and 'container' cannot both be specified. (2) Requirement: Either 'command' or 'container' must be provided (via 'anyOf'). (3) Type constraint: When 'type' is 'stdio' or 'local', either 'command' or 'container' is required. Note: Per-server 'network' field is deprecated and ignored.", "anyOf": [ { "required": ["type"] }, { "required": ["command"] }, { "required": ["container"] } ], "not": { "allOf": [ { "required": ["command"] }, { "required": ["container"] } ] }, "allOf": [ { "if": { "properties": { "type": { "enum": ["stdio", "local"] } } }, "then": { "anyOf": [ { "required": ["command"] }, { "required": ["container"] } ] } } ] }, "http_mcp_tool": { "type": "object", "description": "HTTP MCP tool configuration", "properties": { "type": { "type": "string", "enum": ["http"], "description": "MCP connection type for HTTP" }, "registry": { "type": "string", "description": "URI to the installation location when MCP is installed from a registry", "examples": ["https://api.mcp.github.com/v0/servers/microsoft/markitdown"] }, "url": { "type": "string", "minLength": 1, "description": "URL for HTTP MCP connections" }, "headers": { "type": "object", "patternProperties": { "^[A-Za-z0-9_-]+$": { "type": "string" } }, "additionalProperties": false, "description": "HTTP headers for HTTP MCP connections" }, "allowed": { "type": "array", "description": "List of allowed tool names for this MCP server", "items": { "type": "string" }, "examples": [["*"], ["store_memory", "retrieve_memory"], ["brave_web_search"]] } }, "required": ["url"], "additionalProperties": false }, "github_token": { "type": "string", "pattern": "^\\$\\{\\{\\s*secrets\\.[A-Za-z_][A-Za-z0-9_]*(\\s*\\|\\|\\s*secrets\\.[A-Za-z_][A-Za-z0-9_]*)*\\s*\\}\\}$", "description": "GitHub token expression using secrets. Pattern details: `[A-Za-z_][A-Za-z0-9_]*` matches a valid secret name (starts with a letter or underscore, followed by letters, digits, or underscores). The full pattern matches expressions like `${{ secrets.NAME }}` or `${{ secrets.NAME1 || secrets.NAME2 }}`.", "examples": ["${{ secrets.GITHUB_TOKEN }}", "${{ secrets.CUSTOM_PAT }}", "${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}"] }, "github_app": { "type": "object", "description": "GitHub App credentials for minting installation access tokens.", "properties": { "app-id": { "type": "string", "description": "GitHub App ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App token.", "examples": ["${{ vars.APP_ID }}"] }, "private-key": { "type": "string", "description": "GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to mint a GitHub App token.", "examples": ["${{ secrets.APP_PRIVATE_KEY }}"] }, "owner": { "type": "string", "description": "Optional owner of the GitHub App installation (defaults to current repository owner if not specified)" }, "repositories": { "type": "array", "description": "Optional list of repositories to grant access to (defaults to current repository if not specified)", "items": { "type": "string" } } }, "required": ["app-id", "private-key"], "additionalProperties": false, "examples": [ { "app-id": "${{ vars.APP_ID }}", "private-key": "${{ secrets.APP_PRIVATE_KEY }}" } ] }, "githubActionsStep": { "type": "object", "description": "GitHub Actions workflow step", "properties": { "name": { "type": "string", "description": "A name for your step to display on GitHub" }, "id": { "type": "string", "description": "A unique identifier for the step" }, "if": { "type": "string", "description": "Conditional expression to determine if step should run" }, "uses": { "type": "string", "description": "Selects an action to run as part of a step in your job" }, "run": { "type": "string", "description": "Runs command-line programs using the operating system's shell" }, "with": { "type": "object", "description": "Input parameters defined by the action", "additionalProperties": true }, "env": { "type": "object", "description": "Environment variables for the step", "patternProperties": { "^[A-Za-z_][A-Za-z0-9_]*$": { "type": "string" } }, "additionalProperties": false }, "continue-on-error": { "type": "boolean", "description": "Prevents a job from failing when a step fails" }, "timeout-minutes": { "type": "number", "description": "The maximum number of minutes to run the step before killing the process" }, "working-directory": { "type": "string", "description": "Working directory for the step" }, "shell": { "type": "string", "description": "Shell to use for the run command" } }, "additionalProperties": false, "anyOf": [ { "required": ["uses"] }, { "required": ["run"] } ] }, "checkoutConfig": { "type": "object", "description": "Configuration for a single actions/checkout step", "additionalProperties": false, "properties": { "repository": { "type": "string", "description": "Repository to checkout in owner/repo format. Defaults to the current repository.", "examples": ["owner/repo", "github/gh-aw"] }, "ref": { "type": "string", "description": "Branch, tag, or SHA to checkout. Defaults to the ref that triggered the workflow.", "examples": ["main", "v1.0.0", "feature/my-branch"] }, "path": { "type": "string", "description": "Relative path within GITHUB_WORKSPACE to place the checkout. Defaults to the workspace root.", "examples": [".", "./libs/other-repo", "./workspace"] }, "fetch-depth": { "type": "integer", "minimum": 0, "description": "Number of commits to fetch. 0 fetches all history. 1 (default) is a shallow clone. When multiple configs target the same path, the deepest value is used.", "examples": [0, 1, 10] }, "sparse-checkout": { "type": "string", "description": "Enable sparse-checkout with newline-separated patterns. When multiple configs target the same path, patterns are merged.", "examples": [".github/\nsrc/", "docs/"] }, "submodules": { "oneOf": [ { "type": "string", "enum": ["recursive", "true", "false"] }, { "type": "boolean" } ], "description": "Controls submodule checkout. Use \"recursive\" for all submodules, \"true\" for immediate submodules, or \"false\" to skip." }, "lfs": { "type": "boolean", "description": "Whether to download Git LFS objects. Defaults to false." }, "token": { "type": "string", "description": "Deprecated: Use github-token instead. GitHub token for authentication. Credentials are always removed after checkout (persist-credentials: false is enforced).", "examples": ["${{ secrets.MY_PAT }}", "${{ secrets.GITHUB_TOKEN }}"] }, "github-token": { "type": "string", "description": "GitHub token for authentication. Use ${{ secrets.MY_TOKEN }} to reference a secret. Mutually exclusive with github-app (and deprecated app). Credentials are always removed after checkout (persist-credentials: false is enforced).", "examples": ["${{ secrets.MY_PAT }}", "${{ secrets.CROSS_REPO_PAT }}"] }, "github-app": { "$ref": "#/$defs/github_app", "description": "GitHub App authentication. Mints a short-lived installation access token via actions/create-github-app-token. Mutually exclusive with github-token." }, "current": { "type": "boolean", "description": "Marks this checkout as the logical current repository for the workflow. When set to true, the AI agent will treat this repository as its primary working target. Only one checkout may have current set to true. Useful for central-repo workflows targeting a different repository." }, "fetch": { "oneOf": [ { "type": "string", "description": "A single additional ref pattern to fetch after checkout." }, { "type": "array", "description": "Additional Git refs to fetch after checkout. A git fetch step is emitted after the actions/checkout step.", "items": { "type": "string" } } ], "description": "Additional Git refs to fetch after the checkout. Supported values: \"*\" (all branches), \"refs/pulls/open/*\" (all open pull-request refs), branch names (e.g. \"main\"), or glob patterns (e.g. \"feature/*\").", "examples": [["*"], ["refs/pulls/open/*"], ["main", "feature/my-branch"], ["feature/*"]] } } } } }