Authentication (Projects)

GitHub Projects operations require additional authentication because the default GITHUB_TOKEN is repository-scoped and cannot access the Projects GraphQL API for read or write operations.

Why a separate token is needed

The standard GITHUB_TOKEN provided to every GitHub Actions workflow has repository-level scope only. GitHub Projects (both user-owned and organization-owned) sit outside that scope, so any workflow step that reads project fields or writes updates must supply a token with explicit Projects permissions.

This applies to:

GitHub tools projects toolset — reads project items and field values
update-project safe output — adds items and updates fields
create-project safe output — creates new project boards
create-project-status-update safe output — posts status updates

Personal Access Tokens

User-owned projects

Use a classic PAT with the following scopes:

project
repo (required if the project contains items from private repositories)

Organization-owned projects

Use a fine-grained PAT with these settings:

Resource owner: the organization that owns the project
Repository access: the repositories that will run the workflow
Repository permissions: Contents: Read, and optionally Issues: Read / Pull requests: Read
Organization permissions: Projects: Read and write

GitHub App tokens

For organization-wide standardization, a GitHub App can be used instead of PATs. The app must have Organization projects: Read and write permission.

See Using a GitHub App for Authentication for setup instructions.

Recommended secret layout

Use separate read and write tokens to enforce least privilege:

gh aw secrets set GH_AW_READ_PROJECT_TOKEN --value "<read-token>"
gh aw secrets set GH_AW_WRITE_PROJECT_TOKEN --value "<write-token>"

Reference each token in the workflow where it is needed:

tools:
  github:
    mode: remote
    toolsets: [projects]
    github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }}

safe-outputs:
  update-project:
    project-url: https://github.com/orgs/my-org/projects/1
    github-token: ${{ secrets.GH_AW_WRITE_PROJECT_TOKEN }}

The magic secret GH_AW_GITHUB_MCP_SERVER_TOKEN is recognized by GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow — if it is present in the repository, it is used automatically for all GitHub tools toolsets, including projects.

Authentication — AI engine secrets and GitHub App setup
GitHub Tools — toolset configuration and additional authentication
Safe Outputs — write operations and token configuration
ProjectOps pattern — end-to-end example with project boards