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?

We fully embrace the need for deterministic CI/CD, especially in build, release, and test pipelines. Agentic workflows are 100% additive to your existing CI/CD - they don’t replace or modify your deterministic pipelines.

This is about something new and additive: Continuous AI in addition to Continuous Integration and Continuous Deployment - a new leg to make a trifecta. It just happens to run in GitHub Actions because that’s where infrastructure for secure execution, permissions, and repository context is found. It’s a new addition to your automation toolkit, not a replacement for existing workflows.

Your build, test, and release workflows should remain fully deterministic and reproducible. Agentic workflows complement these by handling tasks that are inherently non-deterministic anyway - like triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review. Many valuable automation tasks don’t require determinism. When a coding agent reviews an issue and suggests a label, or drafts release notes from commits, the exact wording doesn’t need to be reproducible - it needs to be helpful. Agentic workflows excel at these judgment-based tasks while your critical CI/CD pipelines remain unchanged.

Your first call should be reliable, deterministic CI/CD. If you use agentic workflows, you should use them for tasks that benefit from a coding agent’s flexibility, not for core build and release processes that require strict reproducibility.

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 is automatically enabled for public repositories if GH_AW_GITHUB_TOKEN or GH_AW_GITHUB_MCP_SERVER_TOKEN is configured. It is not in effect for private or internal repositories.

See Lockdown Mode for detailed configuration guidance and security considerations.

Configuration & Setup

What is a workflow lock file?

A workflow lock file (.lock.yml) is a traditional GitHub Actions workflow generated for your workflow markdown file (.md). It basically contains scaffolding and guardrails around a coding agent that is going to execute your workflow prompting in GitHub Actions. When you run gh aw compile, the lock file will appear or update and contain a complete GitHub Actions YAML file with all guradrail hardening applied.

Both files should be committed to version control:

• .md file: Your source file - easy to read, edit, and understand
• .lock.yml file: The lock file - what GitHub Actions actually runs

The lock file contains SHA-pinned actions, resolved imports, configured permissions, and all the infrastructure needed for secure execution. You can inspect it to see exactly what will run - there’s no hidden configuration.

The naming convention (.lock.yml) reflects that this file “locks in” the exact workflow configuration at compile time, ensuring reproducibility and auditability. If you modify the frontmatter in your .md file, you must recompile to update the lock file.

When the workflow runs, the prompt itself is taken from the markdown file at runtime, so you can edit the markdown without recompiling and see changes in the next run. However, any changes to frontmatter (permissions, tools, triggers) require recompilation to update the lock file.

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.

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 disable pull request creation by GitHub Actions workflows through repository or organization settings. This security policy prevents automation from creating PRs, resulting in the error: “GitHub Actions is not permitted to create or approve pull requests.”

Organization Setting Location:

• Navigate to your organization’s Settings → Actions → General
• Look for “Workflow permissions” section
• Check if “Allow GitHub Actions to create and approve pull requests” is disabled

Workaround Options:

If you cannot enable PR creation or prefer to keep it disabled for security reasons, you have two alternatives:

Option 1: Use create-issue with automatic fallback (default)

The create-pull-request safe output automatically falls back to creating an issue when PR creation is blocked:

safe-outputs:
  create-pull-request:
    # fallback-as-issue: true is the default behavior
    # When PR creation fails, an issue is created with branch link

This requires both contents: write + pull-requests: write (for PR attempt) and issues: write (for fallback).

Option 2: Use create-issue directly with Copilot coding agent assignment

Create an issue describing the desired changes and assign it to Copilot coding agent for automated implementation:

safe-outputs:
  create-issue:
    assignees: [copilot]              # Assign to Copilot for PR creation
    labels: [automation, enhancement] # Add tracking labels

When assigned to Copilot, the issue can be automatically picked up for processing in a separate workflow or manually reviewed by the Copilot coding agent to create the PR.

Option 3: Disable issue fallback to save permissions

If you only want PR creation (no fallback), disable the issue fallback to avoid requiring issues: write:

safe-outputs:
  create-pull-request:
    fallback-as-issue: false          # Only attempt PR creation

This requires only contents: write + pull-requests: write, but workflows will fail if PR creation is blocked at the organization level.

Tip

For workflows that need to work across different organizations with varying PR policies, use the default fallback-as-issue: true behavior. This ensures workflows gracefully adapt to organization settings.

See Pull Request Creation for complete configuration details and the fallback mechanism explanation.

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.

GitHub Actions prevents the GITHUB_TOKEN from triggering new workflow runs to avoid infinite loops and uncontrolled automation chains. Without this protection, a workflow could create a PR, which triggers another workflow, which creates another PR, and so on indefinitely.

If you need CI checks to run on PRs created by agentic workflows, you have three options:

Option 1: Use different authorization

Configure your create-pull-request safe output to use a PAT or a GitHub App. This allows PR creation to trigger CI workflows.

Option 2: Use workflow_run trigger

Configure your CI workflows to run on workflow_run events, which allows them to react to completed workflows:

on:
  workflow_run:
    workflows: ["Create Pull Request Workflow"]
    types: [completed]

This approach maintains security while allowing CI to run after PR creation. See GitHub Actions workflow_run documentation for details.

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.