Glossary

This glossary provides definitions for key technical terms and concepts used in GitHub Agentic Workflows.

Tip

New to GitHub Agentic Workflows? Technical terms throughout the documentation link to their definitions here. Click any glossary link to understand unfamiliar concepts. Bookmark this page for quick reference!

Core Concepts

Agentic

The term “agentic” means having agency—the ability to act independently, make context-aware decisions, and adapt behavior based on circumstances. When applied to workflows:

• Agentic workflows use AI to understand context and choose appropriate actions, rather than just following predefined steps
• Agentic systems can reason about situations and make informed decisions without explicit programming for every scenario
• Contrasts with deterministic workflows that execute fixed sequences of actions

The word comes from “agent” (an entity that acts on behalf of someone) + “-ic” (having the characteristics of).

Agentic Workflow

An AI-powered workflow that can reason, make decisions, and take autonomous actions using natural language instructions. Unlike traditional workflows with fixed if/then rules, agentic workflows interpret context and adapt their behavior based on the situation they encounter.

Key characteristics:

• Written in natural language markdown instead of complex YAML
• Uses AI to understand repository context (issues, PRs, code)
• Makes context-aware decisions without explicit conditionals
• Adapts responses to different situations flexibly

Example: Instead of “if issue has label X, do Y”, you write “analyze this issue and provide helpful context”, and the AI decides what’s helpful based on the specific issue content.

Agent

The AI system (typically GitHub Copilot CLI) that executes natural language instructions in an agentic workflow. The agent interprets tasks, uses available tools, and generates outputs based on context.

Think of the agent as an AI assistant with access to tools (GitHub API, file system, web search) that can understand your instructions and complete tasks autonomously. The agent is the “intelligence” that makes workflows agentic.

Frontmatter

The configuration section at the top of a workflow file, enclosed between --- markers. Contains YAML settings that control when the workflow runs, what permissions it has, and what tools it can use. Separates technical configuration from natural language instructions.

---
on: issues
permissions: read-all
tools:
  github:
---

Compilation

The process of translating Markdown workflows (.md files) into GitHub Actions YAML format (.lock.yml files). During compilation, workflows are validated, imports are resolved, tools are configured, and security hardening is applied.

Workflow Lock File (.lock.yml)

The compiled GitHub Actions workflow file generated from a workflow markdown file (.md). Contains complete GitHub Actions YAML with security hardening applied. Both the .md source file and .lock.yml compiled file should be committed to version control. GitHub Actions runs the lock file, while the .md file remains easy to read and edit.

Tools and Integration

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

A transparent proxy service that enables unified HTTP access to multiple MCP servers using different transport mechanisms (stdio, HTTP). The gateway provides protocol translation, server isolation, authentication, and health monitoring capabilities. It serves as an intermediary layer between MCP clients expecting HTTP communication and MCP servers that may use various transports, allowing clients to interact with multiple backends through a single HTTP endpoint.

MCP Server

A service that implements the Model Context Protocol to provide specific capabilities to AI agents. Examples include the GitHub MCP server (for GitHub API operations), Playwright MCP server (for browser automation), or custom MCP servers for specialized tools.

Tools

Capabilities that an AI agent can use during workflow execution. Tools are configured in the frontmatter and include GitHub operations (github:), file editing (edit:), web access (web-fetch:, web-search:), shell commands (bash:), browser automation (playwright:), and custom MCP servers.

Security and Outputs

Safe Inputs

Custom MCP tools defined inline in the workflow frontmatter using JavaScript or shell scripts. Allows lightweight tool creation without external dependencies while maintaining controlled access to secrets. Tools are generated at runtime and mounted as an MCP server. Each tool can have typed input parameters, default values, and environment variables. Configured using the safe-inputs: section in frontmatter.

SARIF

Static Analysis Results Interchange Format - a standardized JSON format for reporting results from static analysis tools. Used by GitHub Code Scanning to display security vulnerabilities and code quality issues. Workflows can generate SARIF files using the create-code-scanning-alert safe output to report security findings discovered during AI analysis.

safe-outputs:
  create-code-scanning-alert:
    max: 1

SBOM

Software Bill of Materials - a comprehensive inventory of all components, libraries, and dependencies in a software project. Used for security auditing, vulnerability tracking, and compliance requirements. Helps identify when dependencies have known security issues. Common formats include SPDX and CycloneDX.

Safe Outputs

Pre-approved actions the AI can take without requiring elevated permissions. The AI generates structured output describing what it wants to create (issues, comments, pull requests), which is processed by separate, permission-controlled jobs. Configured using the safe-outputs: section in frontmatter. This approach lets AI agents create GitHub content without direct write access, reducing security risks.

Staged Mode

A preview mode where workflows simulate their actions without making changes. The AI generates output showing what would happen, but no GitHub API write operations are performed. Use for testing and validation before running workflows in production.

Permissions

Access controls that define what operations a workflow can perform. Workflows follow the principle of least privilege, starting with read-only access by default. Write operations are typically handled through safe outputs rather than direct permissions.

Safe Output Messages

Customizable messages that workflows can display during execution to communicate status and progress. Configured in the safe-outputs.messages section. Types include run-started (workflow begins), run-success (workflow completes successfully), run-failure (workflow fails), and footer (appended to all safe outputs). Supports GitHub context variables like {workflow_name} and {run_url}.

safe-outputs:
  messages:
    run-started: "🔍 Analysis starting! [{workflow_name}]({run_url})"
    run-success: "✅ Analysis complete!"
    footer: "> 🤖 *Generated by [{workflow_name}]({run_url})*"

Upload Assets

A safe output capability that allows workflows to upload generated files (screenshots, charts, reports) to an orphaned git branch for persistent storage. Configured in the safe-outputs.upload-assets section. The AI calls the upload_asset tool to register files for upload, which are then committed to a dedicated assets branch by a separate, permission-controlled job. Assets are accessible via predictable GitHub raw URLs. Commonly used for visual testing artifacts, data visualizations, and generated documentation.

safe-outputs:
  upload-asset:
    branch: "assets/my-workflow"     # branch name (default: "assets/${{ github.workflow }}")
    max-size: 10240                  # max file size in KB (default: 10MB)
    allowed-exts: [.png, .jpg, .svg] # allowed extensions

Minimize Comment

A safe output capability that allows workflows to hide or minimize GitHub comments without requiring write permissions. When minimized, comments are classified as SPAM. Requires GraphQL node IDs (format: IC_kwDOABCD123456) to identify comments. Useful for content moderation workflows.

safe-outputs:
  minimize-comment:
    max: 5
    target-repo: "owner/repo"

Workflow Components

Engine

The AI system that powers the agentic workflow. GitHub Agentic Workflows supports multiple engines:

• GitHub Copilot (default): Uses GitHub’s coding assistant

An engine is essentially “which AI to use”—think of it as choosing between different AI assistants (like Copilot, Claude, or others) to execute your workflow instructions.

Triggers

Events that cause a workflow to run. Defined in the on: section of frontmatter. Includes issue events (issues:), pull request events (pull_request:), scheduled runs (schedule:), manual runs (workflow_dispatch:), and comment commands (slash_command:).

Cron Schedule

A time-based trigger format using standard cron syntax with five fields: minute, hour, day of month, month, and day of week.

on:
  schedule:
    - cron: "0 9 * * 1"  # Every Monday at 9 AM UTC

workflow_dispatch

A manual trigger that runs a workflow on demand from the GitHub Actions UI or via the GitHub API. Requires explicit user initiation.

on: workflow_dispatch

Network Permissions

Controls over what external domains and services a workflow can access. Configured using the network: section in frontmatter. Options: defaults (common development infrastructure), custom allow-lists (specific domains), or {} (no network access).

Imports

Reusable workflow components that can be shared across multiple workflows. Specified in the imports: field. Can include tool configurations, common instructions, or security guidelines stored in separate files.

Labels

Optional workflow metadata containing an array of strings for categorization and organization. Labels help organize workflows by topic, purpose, or team, and enable filtering workflows in the CLI using the --label flag.

labels: ["automation", "ci", "diagnostics"]

View workflows with specific labels:

gh aw status --label automation

GitHub and Infrastructure Terms

GitHub Actions

GitHub’s built-in automation platform that runs workflows in response to repository events. Agentic workflows compile to GitHub Actions YAML format, leveraging the existing infrastructure for execution, permissions, and secrets management.

GitHub Projects (Projects v2)

GitHub’s project management and tracking system that organizes issues and pull requests using customizable boards, tables, and roadmaps. Projects v2 provides flexible custom fields (text, number, date, single-select, iteration), automation, and GraphQL API access. Agentic workflows can manage project boards using the update-project safe output to add items, update fields, and maintain campaign tracking. Requires organization-level Projects permissions for API access.

safe-outputs:
  update-project:
    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}

GitHub Actions Secret

A secure, encrypted variable stored in repository or organization settings. Holds sensitive values like API keys or tokens. Access in workflows using ${{ secrets.SECRET_NAME }} syntax.

YAML

A human-friendly data format used for configuration files. Uses indentation and simple syntax to represent structured data. In agentic workflows, YAML appears in the frontmatter section and in compiled .lock.yml files.

Personal Access Token (PAT)

A token that authenticates you to GitHub’s APIs with specific permissions. Required for GitHub Copilot CLI to access Copilot services. Created at github.com/settings/personal-access-tokens.

Agent Files

Markdown files with YAML frontmatter stored in .github/agents/ that define interactive Copilot Chat agents. Created by gh aw init, these files (like create-agentic-workflow.agent.md) can be invoked with the /agent command in Copilot Chat to guide workflow creation with specialized instructions.

Fine-grained Personal Access Token

A type of GitHub Personal Access Token with granular permission control. Specify exactly which repositories the token can access and what permissions it has (contents: read, issues: write, etc.). Created at github.com/settings/personal-access-tokens.

Development and Compilation

CLI (Command Line Interface)

The gh-aw extension for the GitHub CLI (gh) that provides commands for managing agentic workflows: gh aw compile (compile workflows), gh aw run (trigger runs), gh aw status (check status), gh aw logs (download and analyze logs), and gh aw add (add workflows from repositories).

Validation

The process of checking workflow files for errors, security issues, and best practices. Occurs during compilation and can be enhanced with strict mode and security scanners (actionlint, zizmor, poutine).

Advanced Features

Cache Memory

Persistent storage for workflows that preserves data between runs. Configured using cache-memory: in the tools section, it enables workflows to remember information and build on previous interactions.

Agentic campaign

A finite, enterprise-scale initiative with explicit ownership, approval gates, and executive visibility. Agentic campaigns orchestrate business outcomes (security remediation, dependency updates, compliance enforcement) across multiple repositories with governance, accountability, and ROI tracking. Unlike regular workflows that execute operations, agentic campaigns manage business initiatives with measurable outcomes, defined budgets, stakeholder reporting, and compliance audit trails.

Key characteristics:

• Finite duration (days to months) with clear start and end
• Named owners and executive sponsors
• Formal approval gates and change control
• Budget tracking with ROI metrics
• Stateful execution using repo-memory for audit trails
• Cross-team and cross-repository coordination
• Executive dashboards and KPI reporting

File naming: Use .campaign.md extension (e.g., <campaign-id>.campaign.md)

See the Agentic campaigns Guide for implementation patterns and examples.

Command Triggers

Special triggers that respond to slash commands in issue and PR comments (e.g., /review, /deploy). Configured using the slash_command: section with a command name.

Concurrency Control

Settings that limit how many instances of a workflow can run simultaneously. Configured using the concurrency: field to prevent resource conflicts or rate limiting.

Environment Variables (env)

Configuration section in frontmatter that defines environment variables for the workflow. Variables can reference GitHub context values, workflow inputs, or static values. Accessible to all workflow steps via ${{ env.VARIABLE_NAME }} syntax.

env:
  ORGANIZATION: ${{ github.event.inputs.organization || 'github' }}
  API_VERSION: v3

Custom Agents

Specialized instructions or configurations that customize AI agent behavior for specific tasks or repositories. Can be stored as:

• Agent files (.github/agents/*.agent.md) - Used with Copilot Chat /agent command for interactive workflow authoring and execution-time customization
• Instruction files (.github/copilot/instructions/) - Path-specific or repository-wide Copilot instructions

Strict Mode

An enhanced validation mode that enforces additional security checks and best practices. Enabled using strict: true in frontmatter or the --strict flag when compiling.

Timeout

The maximum duration a workflow can run before being automatically cancelled. Configured using timeout-minutes: in frontmatter. Default GitHub Actions timeout is 360 minutes (6 hours); workflows can specify shorter timeouts to fail faster.

timeout-minutes: 45

Tracker ID

A unique identifier assigned to workflows that enables external monitoring and coordination without bidirectional coupling. Campaign orchestrators use tracker IDs to query the GitHub Actions API for workflow runs and discover outputs without workers needing to know about the campaign. This enables tracker-based monitoring where campaigns have knowledge of their workers, but workers operate independently.

tracker-id: daily-file-diet-v1

Toolsets

Predefined collections of related MCP tools that can be enabled together. Used with the GitHub MCP server to group capabilities like repos (repository operations), issues (issue operations), and pull_requests (PR operations). Configured in the toolsets: field under tool configuration.

tools:
  github:
    toolsets:
      - repos
      - issues

Workflow Inputs

Parameters that can be provided when manually triggering a workflow with workflow_dispatch. Defined in the on.workflow_dispatch.inputs section with type, description, default value, and whether the input is required.

on:
  workflow_dispatch:
    inputs:
      organization:
        description: "GitHub organization to scan"
        required: true
        type: string
        default: github

Related Resources

For detailed documentation on specific topics, see:

• Frontmatter Reference
• Tools Reference
• Safe Inputs Reference
• Safe Outputs Reference
• Using MCPs Guide
• Security Guide
• AI Engines Reference