Frequently Asked Questions

Note

GitHub Agentic Workflows is in early development and may change significantly. Using automated agentic workflows 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.

Determinism

I like deterministic CI/CD. Isn’t this non-deterministic?

Agentic workflows are 100% additive to your existing CI/CD - they don’t replace your deterministic build, test, or release pipelines. Think of it as Continuous AI alongside Continuous Integration and Continuous Deployment: a new automation layer running in GitHub Actions where security, permissions, and repository context already exist.

Your deterministic pipelines stay unchanged. Agentic workflows handle tasks where exact reproducibility doesn’t matter - triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review.

Capabilities

What’s the difference between agentic workflows and regular GitHub Actions workflows?

Agentic workflows use AI to interpret natural language instructions in markdown instead of complex YAML. The AI engine can call pre-approved tools to perform tasks while running with read-only default permissions, safe outputs, and sandboxed execution.

What’s the difference between agentic workflows and just running a coding agent in GitHub Actions?

While you could install and run a coding agent directly in a standard GitHub Actions workflow, agentic workflows provide a structured framework with simpler markdown format, built-in security controls, pre-defined tools for GitHub operations, and easy switching between AI engines.

Can agentic workflows write code and create pull requests?

Yes! Agentic workflows can create pull requests using the create-pull-request safe output. This allows the workflow to propose code changes, documentation updates, or other modifications as pull requests for human review and merging.

Some organizations may completely disable the creation of pull requests from GitHub Actions. In such cases, workflows can still generate diffs or suggestions in issues or comments for manual application.

Can agentic workflows do more than code?

Yes! Agentic workflows can 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?

Yes! Agentic workflows can include both AI agentic steps and traditional GitHub Actions steps. You can add custom steps before the agentic job using the steps: configuration. Additionally, custom safe output jobs can be used as consumers of agentic outputs. Safe inputs allow you to pass data between traditional steps and the AI agent with added checking.

Can agentic workflows read other repositories?

Not by default, but yes with proper configuration. Cross-repository access requires:

1. A Personal Access Token (PAT) with access to target repositories
2. Configuring the token in your workflow

See MultiRepoOps for coordinating across repositories, or SideRepoOps for running workflows from a separate repository.

Can I use agentic workflows in private repositories?

Yes, and in many cases we recommend it. Private repositories are ideal for proprietary code, creating a “sidecar” repository with limited access, testing workflows, and organization-internal automation. See SideRepoOps for patterns using private repositories.

Can I edit workflows directly on GitHub.com without recompiling?

Yes! The markdown body (AI instructions) is loaded at runtime and can be edited directly on GitHub.com or in any editor. Changes take effect on the next workflow run without recompilation.

However, frontmatter configuration (tools, permissions, triggers, network rules) is embedded in the compiled workflow and requires recompilation when changed. Run gh aw compile my-workflow after editing frontmatter.

See Editing Workflows for complete guidance on when recompilation is needed.

Can workflows trigger other workflows?

Yes, using the dispatch-workflow safe output:

safe-outputs:
  dispatch-workflow:
    max: 1

This allows your workflow to trigger up to 1 other workflows with custom inputs. See Safe Outputs for details.

Can I use MCP servers with agentic workflows?

Yes! Model Context Protocol (MCP) servers extend workflow capabilities with custom tools and integrations. Configure them in your frontmatter:

tools:
  mcp-servers:
    my-server:
      image: "ghcr.io/org/my-mcp-server:latest"
      network:
        allowed: ["api.example.com"]

See Getting Started with MCP and MCP Servers for configuration guides.

Can workflows be broken up into shareable components?

Workflows can import shared configurations and components:

imports:
  - shared/github-tools.md
  - githubnext/agentics/shared/common-tools.md

This enables reusable tool configurations, network settings, and permissions across workflows. See Imports and Packaging Imports for details.

Can I run workflows on a schedule?

Yes, use cron expressions in the on: trigger:

on:
  schedule:
    - cron: "0 9 * * MON"  # Every Monday at 9am UTC

See Schedule Syntax for cron expression reference.

Can I run workflows conditionally?

Yes, use the if: expression at the workflow level:

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

See Conditional Execution in the Frontmatter Reference for details.

Guardrails

Agentic workflows run in GitHub Actions. Can they access my repository secrets?

Repository secrets are not available to the agentic step by default. The AI agent runs with read-only permissions and cannot directly access your repository secrets unless explicitly configured. You should review workflows carefully, follow GitHub Actions security guidelines, use least-privilege permissions, and inspect the compiled .lock.yml file. See the Security Architectur for details.

Some MCP tools may be configured using secrets, but these are only accessible to the specific tool steps, not the AI agent itself. Minimize the use of tools equipped with highly privileged secrets.

Agentic workflows run in GitHub Actions. Can they write to the repository?

By default, the agentic “coding agent” step of agentic workflows runs with read-only permissions. Write operations require explicit approval through safe outputs or explicit general write permissions (not recommended). This ensures that AI agents cannot make arbitrary changes to your repository.

If safe outputs are configured, the workflow has limited, highly specific write operations that are then sanitized and executed securely.

What sanitization is done on AI outputs before applying changes?

All safe outputs from the AI agent are sanitized before being applied to your repository. Sanitization includes secret redaction, URL domain filtering, XML escaping, size limits, control character stripping, GitHub reference escaping and HTTPS enforcement.

Additionally, safe outputs enforce permission separation - write operations happen in separate jobs with scoped permissions, never in the agentic job itself.

See Safe Outputs - Text Sanitization for configuration options.

Tell me more about guardrails

Guardrails are foundational to the design. Agentic workflows implement defense-in-depth through compilation-time validation (schema checks, expression safety, action SHA pinning), runtime isolation (sandboxed containers with network controls), permission separation (read-only defaults with safe outputs for writes), tool allowlisting, and output sanitization. See the Security Architecture.

How is my code and data processed?

By default, your workflow is run on GitHub Actions, like any other GitHub Actions workflow, and as one if its jobs it invokes your nominated AI Engine (coding agent), run in a container. This engine may in turn make tool calls and MCP calls. When using the default GitHub Copilot CLI, the workflow is processed by the copilot CLI tool which uses GitHub Copilot’s services and related AI models. The specifics depend on your engine choice:

• GitHub Copilot CLI: See GitHub Copilot documentation for details.
• Claude/Codex: Uses respective providers’ APIs with their data handling policies.

See the Security Architecture for details on the execution and data flow.

Does the underlying AI engine run in a sandbox?

Yes, the AI engine runs in a containerized sandbox with network egress control via the Agent Workflow Firewall, container isolation, GitHub Actions resource constraints, and limited filesystem access to workspace and temporary directories. The sandbox container runs inside a GitHub Actions VM for additional isolation. See Sandbox Configuration.

Can an agentic workflow use outbound network requests?

Yes, but network access is restricted by the Agent Workflow Firewall. You must explicitly declare which domains the workflow can access:

network:
  allowed:
    - defaults             # Basic infrastructure
    - python               # Python/PyPI ecosystem
    - "api.example.com"    # Custom domain

See Network Permissions for complete configuration options.

What is GitHub lockdown mode and when is it enabled?

GitHub lockdown mode is a security feature that filters content in public repositories to only show issues, pull requests, and comments from users with push access. This protects workflows from processing potentially malicious input from untrusted users.

Lockdown mode is automatically enabled for public repositories if Additional Authentication for GitHub Tools is configured. It is not in effect for private or internal repositories.

Configuration & Setup

What is a workflow lock file?

A workflow lock file (.lock.yml) is the compiled GitHub Actions workflow generated from your .md file by gh aw compile. It contains SHA-pinned actions, resolved imports, configured permissions, and all guardrail hardening - inspect it to see exactly what will run, with no hidden configuration.

Both files should be committed to version control:

• .md file: Your source - edit the prompt body freely; changes take effect at the next run without recompiling
• .lock.yml file: The compiled workflow GitHub Actions actually runs; must be regenerated after any frontmatter changes (permissions, tools, triggers)

Why do I need a token or key?

When using GitHub Copilot CLI, a Personal Access Token (PAT) with “Copilot Requests” permission authenticates and associates automation work with your GitHub account. This ensures usage tracking against your subscription, appropriate AI permissions, and auditable actions. In the future, this may support organization-level association. See Authentication.

Can I use CLAUDE_CODE_OAUTH_TOKEN with the Claude engine?

No. CLAUDE_CODE_OAUTH_TOKEN is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is ANTHROPIC_API_KEY, which must be configured as a GitHub Actions secret. Provider-based OAuth authentication for Claude (such as billing through a Claude Teams subscription) is not supported. See Authentication and AI Engines for setup instructions.

What hidden runtime dependencies does this have?

The executing agentic workflow uses your nominated coding agent (defaulting to GitHub Copilot CLI), a GitHub Actions VM with NodeJS, pinned Actions from github/gh-aw releases, and an Agent Workflow Firewall container for network control (optional but default). The exact YAML workflow can be inspected in the compiled .lock.yml file - there’s no hidden configuration.

Why are macOS runners not supported?

macOS runners (macos-*) are not currently supported in agentic workflows. Agentic workflows rely on containers to build a secure execution sandbox - specifically the Agent Workflow Firewall that provides network egress control and process isolation. GitHub-hosted macOS runners do not support container jobs, which is a hard requirement for this security architecture.

Use ubuntu-latest (the default) or another Linux-based runner instead. For tasks that genuinely require macOS-specific tooling, consider running those steps in a regular GitHub Actions job that coordinates with your agentic workflow.

I’m not using a supported AI Engine (coding agent). What should I do?

If you want to use a coding agent that isn’t currently supported (Copilot, Claude, or Codex), you can contribute support to the gh-aw repository, or open an issue describing your use case. See AI Engines.

Can I test workflows without affecting my repository?

Yes! Use TrialOps to test workflows in isolated trial repositories. This lets you validate behavior and iterate on prompts without creating real issues, PRs, or comments in your actual repository.

Where can I find help with common issues?

See Common Issues for detailed troubleshooting guidance including workflow failures, debugging strategies, permission issues, and network problems.

Why is my create-discussion workflow failing with integration-forbidden?

Discussion creation requires announcement-capable categories. If your workflow fails with an integration-forbidden error, ensure the category field in your configuration specifies a category that has announcement capabilities enabled in your repository’s discussion settings.

Common issues:

• Non-announcement categories: Only categories configured to support announcements can be used for automated discussion creation. Check your repository’s discussion settings to verify which categories have announcement capabilities.
• Category name typos: Verify the category name spelling in your workflow configuration matches exactly with your repository’s discussion categories. Category names are case-sensitive.
• Category slugs: Use lowercase category slugs (e.g., general, announcements) rather than display names for better reliability.

If discussions are not enabled or the category lacks announcement capabilities, consider using fallback-to-issue: true (the default) to automatically create an issue instead. See Discussion Creation for configuration details.

Why is my create-pull-request workflow failing with “GitHub Actions is not permitted to create or approve pull requests”?

Some organizations block PR creation by GitHub Actions via Settings → Actions → General → Workflow permissions. If you can’t enable it, use one of these alternatives:

Automatic issue fallback (default) — fallback-as-issue: true is the default; when PR creation is blocked an issue with the branch link is created instead. Requires contents: write, pull-requests: write, and issues: write.

Assign to Copilot — create an issue assigned to copilot for automated implementation:

safe-outputs:
  create-issue:
    assignees: [copilot]
    labels: [automation, enhancement]

Disable fallback — set fallback-as-issue: false to skip the issue fallback and only attempt PR creation. Requires only contents: write and pull-requests: write, but the workflow will fail if PR creation is blocked.

See Pull Request Creation for details.

Why don’t pull requests created by agentic workflows trigger my CI checks?

This is expected GitHub Actions security behavior. Pull requests created using the default GITHUB_TOKEN or by the GitHub Actions bot user do not trigger workflow runs on pull_request, pull_request_target, or push events. This is a GitHub Actions security feature designed to prevent accidental recursive workflow execution.

The easy way to fix this problem is to set a secret GH_AW_CI_TRIGGER_TOKEN with a Personal Access Token (PAT) with ‘Contents: Read & Write’ permission to your repo.

See Triggering CI for more details on how to configure workflows to run CI checks on PRs created by agentic workflows.

Workflow Design

Should I focus on one workflow, or write many different ones?

One workflow is simpler to maintain and good for learning, while multiple workflows provide better separation of concerns, different triggers and permissions per task, and clearer audit trails. Start with one or two workflows, then expand as you understand the patterns. See Peli’s Agent Factory for examples.

Should I create agentic workflows by hand editing or using AI?

Either approach works well. AI-assisted authoring using /agent agentic-workflows create in GitHub Copilot Chat provides interactive guidance with automatic best practices, while manual editing gives full control and is essential for advanced customizations. See Creating Workflows for AI-assisted approach, or Reference documentation for manual configuration.

You use ‘agent’ and ‘agentic workflow’ interchangeably. Are they the same thing?

Yes, for the purpose of this technology. An “agent” is an agentic workflow in a repository - an AI-powered automation that can reason, make decisions, and take actions. We use “agentic workflow” as it’s plainer and emphasizes the workflow nature of the automation, but the terms are synonymous in this context.

Costs & Usage

Who pays for the use of AI?

This depends on the AI engine (coding agent) you use:

• GitHub Copilot CLI (default): Usage is currently associated with the individual GitHub account of the user supplying the COPILOT_GITHUB_TOKEN, and is drawn from the monthly quota of premium requests for that account. See GitHub Copilot billing.
• Claude: Usage is billed to the Anthropic account associated with ANTHROPIC_API_KEY Actions secret in the repository.
• Codex: Usage is billed to your OpenAI account associated with OPENAI_API_KEY Actions secret in the repository.

What’s the approximate cost per workflow run?

Costs vary depending on workflow complexity, AI model, and execution time. GitHub Copilot CLI uses 1-2 premium requests per workflow execution with agentic processing. Track usage with gh aw logs for runs and metrics, gh aw audit <run-id> for detailed token usage and costs, or check your AI provider’s usage portal. Consider creating separate PAT/API keys per repository for tracking.

Reduce costs by optimizing prompts, using smaller models, limiting tool calls, reducing run frequency, and caching results.

Can I change the model being used, e.g., use a cheaper or more advanced one?

Yes! You can configure the model in your workflow frontmatter:

engine:
  id: copilot
  model: gpt-5                    # or claude-sonnet-4

Or switch to a different engine entirely:

engine: claude

See AI Engines for all configuration options.