DOCSEARCHbyAlgolia
Submit Docs

GitHub Agentic Workflows

repository·main·Indexed 26 days ago

https://github.com/github/gh-aw

A framework for writing agentic workflows in natural language markdown and executing them within GitHub Actions. Supports multiple AI runtimes including GitHub Copilot, Claude, Codex, and Gemini. Includes tools for building, validating, and scaffolding custom GitHub Actions, as well as a CLI extension and setup actions for managing workflow scripts and environments.

Tokens
273.7K
Snippets
650
Records
1.3K
Agent score
89%

What's inside gh-aw

  1. Overview of MCP Scripts

    main

    MCP Scripts is an extension to the MCP Gateway that allows developers to define custom Model Context Protocol (MCP) tools directly within workflow frontmatter. This enables rapid tool development without the need for external MCP server implementations.

    Key Features:

    • Inline Definition: Define tools using JavaScript, shell scripts, Python, or Go directly in your workflow.
    • Process Isolation: Tools execute in containerized or in-process environments for security.
    • Secret Isolation: Controlled access to secrets via explicit environment variable mapping.
    • Ephemeral Execution: Stateless, containerized tool invocations that clean up after use.

  2. Overview of GitHub Agentic Workflows

    main
    GitHub Agentic Workflows allows you to write repository automation workflows using natural language in Markdown files. These workflows run as GitHub Actions, leveraging AI agents (such as GitHub Copilot, Claude, Gemini, or OpenAI Codex) to perform tasks like automated triage, CI insights, documentation updates, and test enhancements. The system is designed with a security-first approach, using sandboxed execution and layered guardrails to ensure safe automation.

  3. Overview of the stringutil package

    main

    The stringutil package provides a collection of utility functions for string manipulation, sanitization, identifier normalization, ANSI stripping, URL parsing, and GitHub Personal Access Token (PAT) validation. It is organized into specialized sub-files based on functionality:

    • stringutil.go: General string helpers.
    • ansi.go: ANSI escape-code stripping.
    • identifiers.go: Workflow name and path normalization.
    • sanitize.go: Security-sensitive string sanitization.
    • urls.go: URL normalization and domain extraction.
    • pat_validation.go: GitHub PAT classification and validation.
    • fuzzy_match.go: Fuzzy string matching for suggestions.

  4. Overview of the parser package

    main

    The parser package provides tools for processing agentic workflow .md files. It handles:

    • YAML Frontmatter Extraction: Extracts configuration for triggers, permissions, tools, safe outputs, engine settings, network restrictions, and runtime overrides.
    • Markdown Body Processing: Treats the markdown content following the frontmatter as the AI agent's prompt text.
    • Import Resolution: Resolves @import directives which can point to local files, GitHub URLs, or specific fragments.
    • Include Expansion: Expands @include directives located within the markdown body.
    • Schedule Parsing: Converts natural-language schedules into standard cron expressions.
    • MCP Configuration: Extracts Model Context Protocol (MCP) server configurations.
    • Schema Validation: Performs JSON schema–backed validation of workflow files and provides actionable error messages.

    The package is compatible with both the main CLI binary and WebAssembly (Wasm) environments.

  5. Overview of the intent package

    main
    The intent package provides utilities for mapping pull requests and issues to labelled intent records. It uses a Resolver to inspect labels, closing issues, and explicit metadata to classify the intent behind a work item. This allows for routing work items or reporting on coverage based on the resulting IntentRecord.

  6. Overview of Continuous Improvement Workflows

    main

    The gh-aw project includes a suite of autonomous agents designed for continuous repository improvement. These workflows analyze different dimensions of a codebase to ensure long-term health, safety, and quality without requiring manual cleanup sprints.

    Key workflows include:

    • Go Module Usage Expert: Reviews Go dependencies to ensure best practices and feature adoption.
    • Typist: Analyzes Go type usage to improve type safety and reduce duplication.
    • Functional Pragmatist: Applies functional programming patterns (immutability, pure functions, etc.) to improve code clarity.
    • Repository Quality Improver: Performs holistic analysis across various categories like security, performance, and documentation.

  7. Overview of the console Package

    main
    The console package provides terminal UI formatting and rendering utilities for the gh-aw CLI. It includes tools for message formatting, table and section rendering, interactive prompts, progress bars, spinners, and struct rendering. The package is designed with adaptive colors for light/dark themes, TTY detection for automatic adaptation to pipes/redirects, and accessibility support.

  8. Overview of the gh aw CLI extension

    main
    The gh aw CLI extension is the primary user interface for authoring, compiling, running, and monitoring agentic GitHub workflows. It provides a comprehensive set of commands to manage the lifecycle of workflows, from creation and validation to deployment and auditing.

  9. Overview of the linters Package

    main
    The linters package namespace provides a collection of custom static analysis linters used by gh-aw quality checks. These linters are implemented as custom Go analyzers designed to enforce best practices, prevent resource leaks, and simplify code patterns in Go projects.

  10. Overview of ESLint Factory

    main
    ESLint Factory is a project that hosts custom ESLint linters specifically designed to catch recurring JavaScript/TypeScript defects within the /actions/setup/js codebase. It allows for the implementation of custom rules in TypeScript, which are then compiled and executed against the setup scripts.

  11. Understand the Copilot SDK Driver Specification

    main

    The Copilot SDK Driver Specification defines the normative behavior for a driver that runs an agent session against a Copilot SDK endpoint and emits session telemetry. It focuses on environment variable contracts, permission-checking policies, logging requirements, and connection-token propagation.

    This specification is language-agnostic and is intended for developers building drivers that interact with a harness-managed sidecar. Conforming implementations ensure deterministic permission enforcement and interoperable runtime behavior.

  12. Explore companion projects for GitHub Agentic Workflows

    main

    GitHub Agentic Workflows can be extended or secured using the following companion projects:

    • Agent Workflow Firewall (AWF): Provides network egress control for AI agents, including domain-based access controls and activity logging.
    • MCP Gateway: A unified HTTP gateway for routing Model Context Protocol (MCP) server calls, enabling centralized access management.
    • gh-aw-actions: A shared library of custom GitHub Actions used by compiled workflows (e.g., for MCP server file management).