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)

Creating a classic PAT for user-owned private projects

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

Creating a fine-grained PAT for organization-owned projects

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.

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