Text of github.github.com › gh-aw › reference › faq 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

GitHub Agentic Workflows FAQ | GitHub Agentic Workflows

Skip to main content GitHub Agentic Workflows FAQ What is GitHub Agentic Workflows? Section titled “What is GitHub Agentic Workflows?” GitHub Agentic Workflows lets developers define AI-powered repository automation and run AI agents through GitHub Actions. Authors write Markdown instructions with YAML frontmatter, then gh aw compile generates the .lock.yml GitHub Actions workflow. Built-in AI engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi.

Start with the GitHub Agentic Workflows quickstart , learn how to create an agentic workflow , or browse the gallery by repository task . Determinism Section titled “Determinism” I like deterministic CI/CD. Isn’t this non-deterministic? Section titled “I like deterministic CI/CD. Isn’t this non-deterministic?” GitHub Agentic Workflows complements conventional GitHub Actions rather than replacing it. Deterministic Actions workflows remain the right choice for builds, tests, linting, deployments, and reproducible scripts.

Agentic workflows are suited to tasks requiring interpretation, investigation, or generation, such as triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review. Capabilities Section titled “Capabilities” What’s the difference between agentic workflows and regular GitHub Actions workflows? Section titled “What’s the difference between agentic workflows and regular GitHub Actions workflows?” Conventional GitHub Actions workflows define deterministic steps in YAML.

Agentic workflows add an AI agent that interprets natural-language Markdown instructions and calls configured tools. YAML frontmatter still defines triggers, permissions, the AI engine, network access, and safe outputs. What’s the difference between agentic workflows and just running a coding agent in GitHub Actions? Section titled “What’s the difference between agentic workflows and just running a coding agent in GitHub Actions?” A standard Actions workflow can run a coding agent directly.

GitHub Agentic Workflows adds a structured Markdown format, configurable security defaults, predefined GitHub tools, and a common way to select AI engines. Is gh-aw a replacement for GitHub Actions, or does it run on top of it? Section titled “Is gh-aw a replacement for GitHub Actions, or does it run on top of it?” It runs on top of GitHub Actions. gh aw compile turns the Markdown into a .lock.yml workflow, so every run keeps native triggers, runners, logs, and spending limits.

The agent job adds the AI engine plus sandboxing, threat detection, and safe outputs. See How GitHub Agentic Workflows work . Which AI engine should I use? Section titled “Which AI engine should I use?” GitHub Copilot is the default. Claude Code supports fine-grained turn control ( max-turns ). Codex and Gemini use their provider models, and Pi can route to multiple providers but has additional proxy requirements.

Credentials are covered in Who pays for the use of AI? . Compare AI engines before selecting one. Can I run Claude Code on a schedule in GitHub Actions using gh-aw? Section titled “Can I run Claude Code on a schedule in GitHub Actions using gh-aw?” Yes. Set engine: claude in workflow frontmatter, configure ANTHROPIC_API_KEY or Anthropic Workload Identity Federation , and add a schedule trigger such as on: schedule: daily .

See Using Claude Code with GitHub Agentic Workflows . Can agentic workflows write code and create pull requests? Section titled “Can agentic workflows write code and create pull requests?” Yes. The recommended create-pull-request safe output proposes changes for human review through a separate, permission-scoped job. Direct write permissions and custom jobs are separate trust boundaries. If an organization blocks PR creation from GitHub Actions, workflows can still post diffs or suggestions in issues or comments.

Can agentic workflows do more than code? Section titled “Can agentic workflows do more than code?” Yes — analyze repositories, generate reports, triage issues, research information, create documentation, and coordinate work. The AI interprets natural language instructions and uses available tools to accomplish tasks. Can agentic workflows mix regular GitHub Actions steps with AI agentic steps? Section titled “Can agentic workflows mix regular GitHub Actions steps with AI agentic steps?” Yes.

Add custom steps before the agentic job via steps: , consume agentic outputs through custom safe output jobs , and pass typed data between steps and the agent with MCP Scripts . Can agentic workflows read other repositories? Section titled “Can agentic workflows read other repositories?” Yes, with a Personal Access Token (PAT) that has access to target repositories, configured in your workflow. See MultiRepoOps for coordinating across repositories, including running workflows from a separate side repository.

Can I use agentic workflows in private repositories? Section titled “Can I use agentic workflows in private repositories?” Yes. Private repositories support proprietary code, limited-access sidecar repositories, and internal automation. See MultiRepoOps — Side Repository . Can I reuse an agentic workflow outside .github/workflows/ ? Section titled “Can I reuse an agentic workflow outside .github/workflows/?” Not through workflow_call .

GitHub Actions requires reusable workflow YAML files to live directly in .github/workflows/ , with no subdirectories. This GitHub Actions limitation applies to compiled .lock.yml files too, and gh-aw cannot override it. To share a central implementation without copying it, add on: workflow_call to its Markdown, compile it, and commit the .lock.yml under the central repository’s .github/workflows/ . Callers reference that file at the job level: .github/workflows/call-review.yml on : workflow_dispatch jobs : review : uses : my-org/agentic-workflows/.github/workflows/review.lock.yml@v1 secrets : inherit Use a full commit SHA instead of v1 for an immutable reference.

The caller must have access to the reusable workflow and provide the required permissions and engine credentials; secrets: inherit is available within the same organization or enterprise. Imports can move shared configuration and prompts out of entry-point Markdown, but imported files are not independently callable workflows. Can I edit workflows directly on GitHub.com without recompiling? Section titled “Can I edit workflows directly on GitHub.com without recompiling?” Yes, for the markdown body (AI instructions) — loaded at runtime, takes effect on the next run.

Frontmatter (tools, permissions, triggers, network rules) is embedded at compile time and requires gh aw compile my-workflow after edits. See Editing Workflows . How can I use parameters in a workflow prompt? Section titled “How can I use parameters in a workflow prompt?” Declare workflow_dispatch inputs for values chosen when starting a run, or use workflow-level env for values configured in one place. Reference them with GitHub Actions expressions in the markdown body: --- on : workflow_dispatch : inputs : branch : description : Branch to report on type : string default : main env : PRODUCT : Contoso --- Build a report for ${{ env.PRODUCT }} on branch ${{ inputs.branch }}.

The prompt is populated with the input and environment values before the agent receives it. A shell-style placeholder such as ${PRODUCT} in the markdown body is not expanded; use ${{ env.PRODUCT }} instead. Recompile after changing frontmatter values or input definitions. Can workflows trigger other workflows? Section titled “Can workflows trigger other workflows?” Yes, using the dispatch-workflow safe output (default max: 1 ): safe-outputs : dispatch-workflow : max : 1 See Safe Outputs .

Can I trigger an agentic workflow from an external system like Jira? Section titled “Can I trigger an agentic workflow from an external system like Jira?” Yes.

The rest of this page is on the live site.