What is the purpose of repository-projects permission in GITHUB_TOKEN?

[Dzieni]

Select Topic Area

Question

Body

A part of the docs claim, that

GITHUB_TOKEN is scoped to the repository level and cannot access projects.

But in the other part of the docs I see that there is a permission called repository-projects. There are no more details about it, but the name suggests that it should allow accessing the projects that are linked to the repository you're running the action from.

Unfortunately, it does not work. Here is a demo: https://github.com/Dzieni/github-actions-permission-test

It contains a really simple workflow based on the minimal example of octokit/graphql-action:

name: Log repository projects
on:
  push:
    branches:
      - main

permissions: read-all

jobs:
  logRepoProjects:
    runs-on: ubuntu-latest
    steps:
      - uses: octokit/graphql-action@v2.x
        id: get_projects
        with:
          query: |
            query projects($owner: String!, $repo: String!) {
              repository(owner: $owner, name: $repo) {
                projectsV2(first: 50) {
                  nodes {
                    id
                    title
                  }
                }
              }
            }
          owner: ${{ github.event.repository.owner.name }}
          repo: ${{ github.event.repository.name }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: "echo 'project release: ${{ steps.get_projects.outputs.data }}'"

When you go to the projects section, you can see that the repo has at least one project:

Then the workflow run has following permissions (note RepositoryProjects):

  Actions: read
  Checks: read
  Contents: read
  Deployments: read
  Discussions: read
  Issues: read
  Metadata: read
  Packages: read
  Pages: read
  PullRequests: read
  RepositoryProjects: read
  SecurityEvents: read
  Statuses: read

However, the result is an empty list of projects. It does work when using a personal token instead of the GITHUB_TOKEN.

Therefore - if repository-projects does not list projects from a given repo, then what is the actual purpose? It would be great if such an information was included in the docs.

[jsoref]

https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-projects

[Dzieni]

OK, so a) only REST API, b) only classic projects (which you cannot even create anymore).

Is there a similar document for GraphQL API?

[jsoref]

Shrug. That page covers all permissions, more or less. If the v4 API explanation of permissions is insufficient, you can file a bug against GitHub/docs or some similar repository.

[jayarjo]

I encounter this as well. @Dzieni have you filed a bug or had any progress on this?

[muzimuzhi]

repository-projects permission is for working with GitHub projects (classic).

On writing this, this permission has been removed from both the workflow syntax and REST API docs. See github/docs@1d7c2fe (Remove mentions of Projects (classic) and associated features (#55017), 2025-04-10).

Also according to this GitHub changelog, the Projects (classic)

• should already be sunset for GitHub.com, GitHub CLI, and the REST API before the start of 2026;
• will be removed in GitHub Enterprise Server version 3.17.

Remaining docs found in github/docs repo

https://github.com/github/docs/blob/4154a54894452b376b79221173e3f9225e6d384c/data/reusables/actions/github-token-available-permissions.md?plain=1#L18

pull-requests: read\|write\|none{% ifversion projects-v1 %}
repository-projects: read\|write\|none{% endif %}

https://github.com/github/docs/blob/4154a54894452b376b79221173e3f9225e6d384c/data/reusables/actions/github-token-scope-descriptions.md?plain=1#L29

| {% ifversion projects-v1 %} |
|  `repository-projects` | Work with GitHub projects (classic). For example, `repository-projects: write` permits an action to add a column to a project (classic). For more information, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-projects). |
| {% endif %} |