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

Open the live page

Glossary | GitHub Agentic Workflows

Skip to main content Glossary Definitions of key terms used in GitHub Agentic Workflows, a system for running AI-powered repository automation through GitHub Actions. Core Concepts Section titled “Core Concepts” Agentic Section titled “Agentic” Having agency - the ability to act independently, make context-aware decisions, and adapt behavior based on circumstances. Agentic workflows use AI to understand context and choose appropriate actions, contrasting with deterministic workflows that execute fixed sequences.

From “agent” + “-ic” (having the characteristics of). Agentic Workflow Section titled “Agentic Workflow” AI-powered repository automation that runs an AI agent through GitHub Actions. An agentic workflow is authored primarily as Markdown instructions with YAML frontmatter for triggers, permissions, tools, the AI engine, and controlled outputs. For example, instead of “if issue has label X, do Y”, an author can ask the AI agent to analyze an issue and provide context based on its specific content.

Orchestration Section titled “Orchestration” Workflows that coordinate one or more worker workflows toward a shared goal. An orchestrator decides what work to do next and dispatches workers, while workers execute concrete tasks with scoped tools and limits. See the OrchestratorOps pattern . Orchestrator Workflow Section titled “Orchestrator Workflow” A workflow that fans out work by dispatching other workflows (workers), aggregates results, and optionally posts summaries.

Worker Workflow Section titled “Worker Workflow” A workflow dispatched by an orchestrator that performs a focused unit of work (triage, analysis, code changes, validation). AI Agent Section titled “AI Agent” The reasoning component that interprets an agentic workflow’s natural-language instructions, uses configured tools, and generates outputs from repository context. GitHub Actions runs the AI agent through a selected AI engine .

Frontmatter Section titled “Frontmatter” Configuration section at the top of a workflow file, enclosed between --- markers. Contains YAML settings controlling when the workflow runs, permissions, and available tools, separating technical configuration from natural language instructions. Intent ( intent: ) Section titled “Intent (intent:)” Optional frontmatter field describing the durable adoption a workflow exists to achieve, rendered as a comment in the generated lock file.

Unlike description , which explains what the workflow does, intent explains why it exists and stays implementation-independent, so it remains valid even as the workflow’s implementation changes. Compilation Section titled “Compilation” Translating Markdown workflows ( .md files) into GitHub Actions YAML format ( .lock.yml files), including validation, import resolution, tool configuration, and security hardening.

Workflow Lock File (.lock.yml) Section titled “Workflow Lock File (.lock.yml)” The compiled GitHub Actions workflow file from a workflow markdown file ( .md ). Contains complete GitHub Actions YAML with security hardening applied. Both .md and .lock.yml files should be committed to version control. At runtime, GitHub Actions executes the lock file using a coding agent while referencing the markdown for instructions.

Lock File Exclusion ( exclude-lock-yml ) Section titled “Lock File Exclusion (exclude-lock-yml)” A create-pull-request and push-to-pull-request-branch safe-output option that omits compiled .lock.yml files under .github/workflows/ from patch and bundle transports. It avoids GitHub’s workflow-write restriction when the GitHub Actions token publishes changes. Other workflow YAML files are not excluded and still require workflow-write credentials.

When exclusions drop changes, the pull request body warns to re-run gh aw compile and commit the regenerated locks with authorized credentials. See Safe Outputs (Pull Requests) . Actions Lock Integration ( --actions-lock ) Section titled “Actions Lock Integration (--actions-lock)” A gh aw compile flag that runs the separately installed gh actions-lock extension after compilation to update .github/workflows/actions.lock .

The extension scans all workflows in its default directory, and compilation never installs it. The flag is incompatible with --no-emit , --read-only , --watch , and --dry-run , and does not replace .github/aw/actions-lock.json . See CLI Commands . Tools and Integration Section titled “Tools and Integration” MCP (Model Context Protocol) Section titled “MCP (Model Context Protocol)” A standardized protocol that allows AI agents to securely connect to external tools, databases, and services.

MCP enables workflows to integrate with GitHub APIs, web services, file systems, and custom integrations while maintaining security controls. MCP Gateway Section titled “MCP Gateway” A transparent proxy service that enables unified HTTP access to multiple MCP servers using different transport mechanisms (stdio, HTTP). Provides protocol translation, server isolation, authentication, and health monitoring, allowing clients to interact with multiple backends through a single HTTP endpoint.

Trusted Bots ( sandbox.mcp.trusted-bots ) Section titled “Trusted Bots (sandbox.mcp.trusted-bots)” A frontmatter field that passes additional GitHub bot identity strings to the MCP Gateway . The gateway merges these with its built-in trusted identity list to determine which bot identities are permitted. This field is additive — it can only extend the gateway’s internal list, not remove built-in entries. Configured under sandbox.mcp: and compiled into the trustedBots array in the generated gateway configuration.

Example entries: github-actions[bot] , copilot-swe-agent[bot] . See MCP Gateway Reference . MCP Gateway Environment Injection Section titled “MCP Gateway Environment Injection” The mechanism that transports sandbox.mcp.env custom environment variable values from workflow frontmatter into the MCP Gateway’s Docker container. Values are routed through compiler-controlled, indexed transport variables ( GH_AW_MCP_GATEWAY_ENV_0 , GH_AW_MCP_GATEWAY_ENV_1 , …) and a companion manifest variable ( GH_AW_MCP_GATEWAY_CUSTOM_ENV_NAMES ), rather than being interpolated directly into the generated shell script or Docker command string.

A JavaScript launcher ( start_mcp_gateway.cjs ) reads the manifest and reconstructs atomic -e NAME=VALUE Docker arguments at runtime. Both the Go compiler and the JS launcher validate variable names against ^[A-Z_][A-Z0-9_]*$ , preventing shell metacharacters or dangerous names (such as BASH_ENV ) in custom values from being sourced or interpreted before the gateway process starts. See MCP Gateway Reference . Agent Identifier Configuration ( agentId , agentIds ) Section titled “Agent Identifier Configuration (agentId, agentIds)” A MCP Gateway configuration setting that identifies the agent or session(s) authenticating through the gateway. agentId specifies a single string identifier; agentIds specifies an array of one or more identifiers, enabling a primary agent and enclave sessions to share one gateway instance while retaining independent DIFC state and policies.

Exactly one of the two fields must be present in a given gateway configuration — specifying both, or neither, is rejected as invalid. Both replace the legacy api_key / apiKey spelling in generated configuration. See MCP Gateway Reference . MCP Gateway Mount-Roots Allowlist ( MCP_GATEWAY_ALLOWED_MOUNT_ROOTS ) Section titled “MCP Gateway Mount-Roots Allowlist (MCP_GATEWAY_ALLOWED_MOUNT_ROOTS)” The compiler-computed value that authorizes host-path mounts for MCP backend server containers under the gateway’s trusted host-path mount policy. buildMCPGatewayAllowedMountRoots collects every mount surface the compiler configures — the built-in workspace, gh-aw runtime, safeoutputs, and temp paths, gateway-level sandbox.mcp.mounts , and per-server mounts

The rest of this page is on the live site.