Permissions

The permissions: section controls what GitHub API operations your workflow can perform. GitHub Agentic Workflows uses read-only permissions by default for security, with write operations handled through safe outputs.

permissions:
  contents: read
  actions: read
safe-outputs:
  create-issue:
  add-comment:

Permission Model

Security-First Design

Agentic workflows follow a principle of least privilege:

• Read-only by default: Main job runs with minimal read permissions only
• Write through safe outputs: Write operations happen in separate jobs with sanitized content
• No direct write permissions: Use safe-outputs instead of write permissions in the main job

This model prevents AI agents from accidentally or maliciously modifying repository content during execution.

Permission Scopes

Key permissions include contents (code access), issues (issue management), pull-requests (PR management), discussions, actions (workflow control), checks, deployments, packages, pages, and statuses. Each has read and write levels. See GitHub’s permissions reference for the complete list.

Configuration

Basic Configuration

Specify individual permission levels:

permissions:
  contents: read
  actions: read
safe-outputs:
  create-issue:

Shorthand Options

• read-all: Read access to all scopes (useful for inspection workflows)
• {}: No permissions (for computation-only workflows)

Caution

Avoid using write-all or direct write permissions in agentic workflows. Use safe outputs instead for secure write operations.

Common Patterns

All workflows should use read-only permissions with safe outputs for write operations:

# IssueOps: Read code, comment via safe outputs
permissions:
  contents: read
  actions: read
safe-outputs:
  add-comment:
    max: 5

# PR Review: Read code, review via safe outputs
permissions:
  contents: read
  actions: read
safe-outputs:
  create-pr-review-comment:
    max: 10

# Scheduled: Analysis with issue creation via safe outputs
permissions:
  contents: read
  actions: read
safe-outputs:
  create-issue:
    max: 3

# Manual: Admin tasks with approval gate
permissions: read-all
manual-approval: production

Safe Outputs

Write operations use safe outputs instead of direct API access. This provides content sanitization, rate limiting, audit trails, and security isolation by separating write permissions from AI execution. See Safe Outputs for details.

Permission Validation

Run gh aw compile workflow.md to validate permissions. Common errors include undefined permissions, direct write permissions in the main job (use safe outputs instead), and insufficient permissions for declared tools. Use --strict mode to enforce read-only permissions and require explicit network configuration.

Tool-Specific Requirements

Some tools require specific permissions to function:

• agentic-workflows: Requires actions: read to access workflow logs and run data
• GitHub MCP toolsets: See Tools for GitHub API permission requirements

The compiler validates these requirements and provides clear error messages when permissions are missing.

Related Documentation

• Safe Outputs - Secure write operations with content sanitization
• Security Guide - Security best practices and permission strategies
• Tools - GitHub API tools and their permission requirements
• Frontmatter - Complete frontmatter configuration reference