Authentication (Projects) | GitHub Agentic Workflows
Skip to main content 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 Section titled “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 Section titled “Personal Access Tokens” User-owned projects Section titled “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 Section titled “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 Section titled “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 Section titled “Recommended secret layout” Use separate read and write tokens to enforce least privilege: Terminal window 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 .
Learn More Section titled “Learn More” 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