Authentication (Projects)

Project operations require additional authentication since the default GITHUB_TOKEN lacks necessary permissions for the Projects API. You can authenticate using either a Personal Access Token (PAT) or a GitHub App token.

Using a Personal Access Token (PAT)

1. Create the PAT

   For User-owned Projects:

   Create a classic PAT with scopes:

   • project (required for user Projects)
   • repo (required if accessing private repositories)

   For Organization-owned Projects (v2):

   Create a fine-grained PAT with:

   • Repository access: Select specific repos that will use the workflow
   • Repository permissions:
     • Contents: Read
     • Issues: Read (if needed for issue-triggered workflows)
     • Pull requests: Read (if needed for PR-triggered workflows)
   • Organization permissions (must be explicitly granted):
     • Projects: Read & Write (required for updating org Projects)
   • Important: You must explicitly grant organization access during token creation

2. Add the token to repository secrets

   gh aw secrets set MY_PROJECT_TOKEN --value "YOUR_PROJECT_PAT"

3. Configure in your workflow frontmatter

   safe-outputs:
     update-project:
       github-token: ${{ secrets.MY_PROJECT_TOKEN }}
   
   tools:
     github:
       toolsets: [default, projects]
       github-token: ${{ secrets.MY_PROJECT_TOKEN }}

Using a GitHub App

Alternatively, you can use a GitHub App for enhanced security. See Using a GitHub App for Authentication for complete setup instructions. Once set up, reference the app token in your workflow using app: on safe outputs and tools.

Using a magic secret

Alternatively, you can set the magic GitHub Actions secret GH_AW_PROJECT_GITHUB_TOKEN to a suitable PAT (see the above guide for creating a suitable PAT). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow.

gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "<your-pat-token>"

Creating a classic PAT for user-owned private projects

Creating a fine-grained PAT for organization-owned projects

Debugging: who owns a GitHub token?

Ownership affects token requirements for projects. If the owner is your personal username, it is user-owned. If the owner is an organization, it is org-owned and managed with shared roles and access controls.

To confirm ownership, check the owner name and avatar at the top of the page or in the URL (github.com/owner-name/...). Clicking the owner takes you to a personal profile or an organization page, which confirms it instantly. Here are examples of both (left: user-owned, right: org-owned):

User-owned repository

Avatar shows a personal profile icon, URL includes username

Organization-owned repository

Avatar shows organization icon, URL includes org name

Related

• Authentication - General authentication reference
• ProjectOps - Automate GitHub Projects with AI-powered workflows
• Safe Outputs Reference - Project update configuration