gh-aw

module
v0.75.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 22, 2026 License: MIT

README

GitHub Agentic Workflows

Write agentic workflows in natural language markdown, and run them in GitHub Actions.

[!NOTE] Releases 0.68.4 through 0.71.3 are being retired due to a bug that impacts billing. If you are running one of these versions, please upgrade to the latest release as soon as possible.

Contents

Quick Start

Ready to get your first agentic workflow running? Follow our step-by-step Quick Start Guide to install the extension, add a sample workflow, and see it in action.

Overview

Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See How It Works. Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) — pick whichever AI account you already have.

Guardrails

Guardrails, safety and security are foundational to GitHub Agentic Workflows. Workflows run with read-only permissions by default, with write operations only allowed through sanitized safe-outputs. The system implements multiple layers of protection including sandboxed execution, input sanitization, network isolation, supply chain security (SHA-pinned dependencies), tool allow-listing, and compile-time validation. Access can be gated to team members only, with human approval gates for critical operations, ensuring AI agents operate safely within controlled boundaries. See the Security Architecture for comprehensive details on threat modeling, implementation guidelines, and best practices.

Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.

Documentation

For complete documentation, examples, and guides, see the Documentation. If you are an agent, download llms.txt or the full corpus llms-full.txt.

If you are running a version between 0.68.4 and 0.71.3, upgrading is strongly recommended due to a bug that impacts billing.

Contributing

For development setup and contribution guidelines, see CONTRIBUTING.md.

Custom Go linters

To build and test repository custom linters:

  • go test ./pkg/linters/<linter-name>/...
  • go build ./cmd/linters
  • make golint-custom

make golint-custom builds cmd/linters and runs the custom analyzers against ./cmd/... and ./pkg/....

🌍 Community Contributions

Thank you to the community members whose issue reports were resolved in this project! This list is updated automatically and reflects all attributed contributions.
⚠️ Attribution Candidates Need Review

The following community issues were closed during this period but could not be automatically linked to a specific merged PR. Please verify whether they should be credited:

  • @app/github-actions for #32423 — closed 2026-05-15, no confirmed PR linkage found
  • @app/github-actions for #31178 — closed 2026-05-14, no confirmed PR linkage found
  • @askpaisa for #28389 — closed 2026-04-25, no confirmed PR linkage found
  • @JamesNK for #28868 — closed 2026-04-30, no confirmed PR linkage found
  • @jobayer-4 for #32608 — closed 2026-05-16, no confirmed PR linkage found

Share Feedback

We welcome your feedback on GitHub Agentic Workflows!

Peli's Agent Factory

See the Peli's Agent Factory for a guided tour through many uses of agentic workflows.

GitHub Agentic Workflows is supported by companion projects that provide additional security and integration capabilities:

  • Agent Workflow Firewall (AWF) - Network egress control for AI agents, providing domain-based access controls and activity logging for secure workflow execution
  • MCP Gateway - Routes Model Context Protocol (MCP) server calls through a unified HTTP gateway for centralized access management
  • gh-aw-actions - Shared library of custom GitHub Actions used by compiled workflows, providing functionality such as MCP server file management

Directories

Path Synopsis
cmd
gh-aw command
gh-aw-wasm command
linters command
Command linters runs the gh-aw custom analysis linters.
 Command linters runs the gh-aw custom analysis linters.
internal
tools/actions-build command
tools/generate-action-metadata command
pkg
actionpins
Package actionpins provides action pin resolution for GitHub Actions, mapping repository references to their pinned commit SHAs.
 Package actionpins provides action pin resolution for GitHub Actions, mapping repository references to their pinned commit SHAs.
agentdrain
cli
Package cli provides the command-line interface for gh-aw (GitHub Agentic Workflows).
 Package cli provides the command-line interface for gh-aw (GitHub Agentic Workflows).
console
Package console provides terminal UI components and formatting utilities for the gh-aw CLI.
 Package console provides terminal UI components and formatting utilities for the gh-aw CLI.
constants
envutil
Package envutil provides utilities for reading and validating environment variables.
 Package envutil provides utilities for reading and validating environment variables.
errorutil
Package errorutil provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.
 Package errorutil provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.
fileutil
Package fileutil provides utility functions for working with file paths and file operations.
 Package fileutil provides utility functions for working with file paths and file operations.
gitutil
jsonutil
linters
Package linters is a namespace for gh-aw's custom Go analysis linters.
 Package linters is a namespace for gh-aw's custom Go analysis linters.
linters/ctxbackground
Package ctxbackground implements a Go analysis linter that flags calls to context.Background() inside functions that already receive a context.Context parameter.
 Package ctxbackground implements a Go analysis linter that flags calls to context.Background() inside functions that already receive a context.Context parameter.
linters/errormessage
Package errormessage implements a Go analysis linter that enforces actionable error-message patterns in changed files.
 Package errormessage implements a Go analysis linter that enforces actionable error-message patterns in changed files.
linters/errstringmatch
Package errstringmatch implements a Go analysis linter that flags calls to strings.Contains(err.Error(), "literal") that perform brittle substring matching on error messages instead of using errors.Is or errors.As.
 Package errstringmatch implements a Go analysis linter that flags calls to strings.Contains(err.Error(), "literal") that perform brittle substring matching on error messages instead of using errors.Is or errors.As.
linters/excessivefuncparams
Package excessivefuncparams implements a Go analysis linter that flags functions with too many positional parameters.
 Package excessivefuncparams implements a Go analysis linter that flags functions with too many positional parameters.
linters/fileclosenotdeferred
Package fileclosenotdeferred implements a Go analysis linter that flags file operations where Close() is not immediately deferred.
 Package fileclosenotdeferred implements a Go analysis linter that flags file operations where Close() is not immediately deferred.
linters/internal/filecheck
linters/internal/nolint
Package nolint provides shared helpers for nolint-directive detection used by linters within pkg/linters.
 Package nolint provides shared helpers for nolint-directive detection used by linters within pkg/linters.
linters/largefunc
Package largefunc implements a Go analysis linter that flags functions whose body exceeds a configurable line threshold.
 Package largefunc implements a Go analysis linter that flags functions whose body exceeds a configurable line threshold.
linters/osexitinlibrary
Package osexitinlibrary implements a Go analysis linter that flags os.Exit calls in library (pkg/) packages.
 Package osexitinlibrary implements a Go analysis linter that flags os.Exit calls in library (pkg/) packages.
linters/rawloginlib
Package rawloginlib implements a Go analysis linter that flags standard log package calls in library (pkg/) packages.
 Package rawloginlib implements a Go analysis linter that flags standard log package calls in library (pkg/) packages.
linters/regexpcompileinfunction
Package regexpcompileinfunction implements a Go analysis linter that flags calls to regexp.MustCompile() and regexp.Compile() inside function bodies.
 Package regexpcompileinfunction implements a Go analysis linter that flags calls to regexp.MustCompile() and regexp.Compile() inside function bodies.
linters/ssljson
Package ssljson implements a Go analysis linter that validates .github/skills/*/ssl.json files against the SSL specification rules.
 Package ssljson implements a Go analysis linter that validates .github/skills/*/ssl.json files against the SSL specification rules.
logger
Package logger provides namespace-based debug logging with zero overhead when disabled.
 Package logger provides namespace-based debug logging with zero overhead when disabled.
parser
Package parser provides markdown frontmatter parsing and content extraction for agentic workflow files.
 Package parser provides markdown frontmatter parsing and content extraction for agentic workflow files.
repoutil
Package repoutil provides utility functions for working with GitHub repository slugs and URLs.
 Package repoutil provides utility functions for working with GitHub repository slugs and URLs.
semverutil
Package semverutil provides shared semantic versioning primitives used across the pkg/workflow and pkg/cli packages.
 Package semverutil provides shared semantic versioning primitives used across the pkg/workflow and pkg/cli packages.
sliceutil
Package sliceutil provides utility functions for working with slices.
 Package sliceutil provides utility functions for working with slices.
stats
Package stats provides numerical statistics utilities for metric collection.
 Package stats provides numerical statistics utilities for metric collection.
stringutil
Package stringutil provides utility functions for working with strings.
 Package stringutil provides utility functions for working with strings.
styles
Package styles provides centralized style and color definitions for terminal output.
 Package styles provides centralized style and color definitions for terminal output.
syncutil
testutil
timeutil
tty
Package tty provides utilities for TTY (terminal) detection.
 Package tty provides utilities for TTY (terminal) detection.
types
Package types provides shared type definitions used across gh-aw packages.
 Package types provides shared type definitions used across gh-aw packages.
typeutil
Package typeutil provides general-purpose type conversion utilities.
 Package typeutil provides general-purpose type conversion utilities.
workflow
Package workflow implements workflow compilation orchestration.
 Package workflow implements workflow compilation orchestration.
smoke_test_22524436360.go - smoke test file for run 22524436360 This file was automatically created during smoke testing and can be safely removed.
 smoke_test_22524436360.go - smoke test file for run 22524436360 This file was automatically created during smoke testing and can be safely removed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.