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.

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

Use a classic PAT with the following scopes:

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

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

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.

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