Missing "endpoints" and "permissions" documentation for `REST API endpoints for teams`

tonglil commented 3 months ago

Code of Conduct

[X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

For the endpoints and permissions specified in REST API endpoints for teams (https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#add-or-update-team-repository-permissions), they are not documented on the following pages:

For example, if you search for the (i guess older?) endpoints that contain {team_slug} and some others:

/orgs/{org}/teams/{team_slug}
/orgs/{org}/teams/{team_slug}/projects
/orgs/{org}/teams/{team_slug}/projects/{project_id}
/orgs/{org}/teams/{team_slug}/repos
/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}
/orgs/{org}/teams/{team_slug}/teams
/user/teams

They do not appear on those pages.

What changes are you suggesting?

Document them, because some of them work with Fine-grained personal access tokens and some don't, and some work with GitHub App installation access tokens and some don't.

It's really confusing because crucially the ability to create a repo and assign a team with admin permission to it is only seemingly available through PUT /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo} with personal access tokens (classic and fine-grained), but not available to a GitHub App installed in an organization, which seems like a big gap and an issue for organizations that restrict access with PATs and want to automate actions on GitHub through GitHub Apps.

Furthermore, creating a new repo with the team_id only grants that team read access, which is not useful (see: https://github.com/github/rest-api-description/issues/3689).

Overall it seems like this aspect of the documentation has been neglected.

Additional information

No response

nguyenalex836 commented 3 months ago

@tonglil Thanks for opening an issue! I'll get this triaged for review ✨

HSUYATANG commented 3 months ago

謝謝你好的

felicitymay commented 1 month ago

@tonglil - many thanks for highlighting this gap in the docs, and for your patience as we've been so slow to review this issue.

Since this is in the REST API docs, which are automatically populated from our OpenAPI schema, we're going to need to make a copy of this issue internally too.

docs-bot commented 1 month ago

Thank you for opening this issue! Updates to this documentation must be made internally. I have copied your issue to an internal issue, so I will close this issue.

github / docs