GitHub Tools Read 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:

This separation provides an audit trail, limits blast radius if an agent misbehaves, supports compliance approval gates, and defends against prompt injection. Safe outputs add one extra job but provide critical safety guarantees.

Permission Scopes

Key read permission scopes include:

• contents (code access)
• issues (issue management)
• pull-requests (PR management)
• discussions (discussions and comments)
• actions (workflow control)
• checks (checks and statuses)
• deployments (deployment management)
• packages (package management)
• pages (GitHub Pages management)
• statuses (commit status management)

See GitHub’s permissions reference for the complete list.

Shorthand Options:

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

GitHub App-Only Permissions

Certain permission scopes require additional authentication. These include:

Repository-level: administration, environments, git-signing, vulnerability-alerts, workflows, repository-hooks, single-file, codespaces, repository-custom-properties

Organization-level: organization-projects, members, organization-administration, team-discussions, organization-hooks, organization-members, organization-packages, organization-self-hosted-runners, organization-custom-org-roles, organization-custom-properties, organization-custom-repository-roles, organization-announcement-banners, organization-events, organization-plan, organization-user-blocking, organization-personal-access-token-requests, organization-personal-access-tokens, organization-copilot, organization-codespaces

User-level: email-addresses, codespaces-lifecycle-admin, codespaces-metadata

These scopes must always be declared as read.

Special Permission: id-token

The id-token permission controls access to GitHub’s OIDC token service for OpenID Connect (OIDC) authentication with cloud providers (AWS, GCP, Azure).

The only valid values are write and none. id-token: read is not a valid permission and will be rejected at compile time.

Unlike other write permissions, id-token: write does not grant any ability to modify repository content. It only allows the workflow to request a short-lived OIDC token from GitHub’s token service for authentication with external cloud providers.

# Example: Deploy to AWS using OIDC authentication
permissions:
  id-token: write      # Allowed for OIDC authentication
  contents: read       # Read repository code

This permission does not require safe-outputs.

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