Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing "endpoints" and "permissions" documentation for REST API endpoints for teams #33635

Closed
1 task done
tonglil opened this issue Jun 21, 2024 · 4 comments
Closed
1 task done
Labels
content This issue or pull request belongs to the Docs Content team fix-internally Triggers a workflow to copy the issue internally and close the current issue rest Content related to rest - overview.

Comments

@tonglil
Copy link

tonglil commented Jun 21, 2024

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: github/rest-api-description#3689).

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

Additional information

No response

@tonglil tonglil added the content This issue or pull request belongs to the Docs Content team label Jun 21, 2024
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Jun 21, 2024
@nguyenalex836
Copy link
Contributor

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

@nguyenalex836 nguyenalex836 added waiting for review Issue/PR is waiting for a writer's review rest Content related to rest - overview. and removed triage Do not begin working on this issue until triaged by the team labels Jun 21, 2024
@HSUYATANG

This comment was marked as spam.

@felicitymay
Copy link
Contributor

@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.

@felicitymay felicitymay added fix-internally Triggers a workflow to copy the issue internally and close the current issue and removed waiting for review Issue/PR is waiting for a writer's review labels Aug 19, 2024
@docs-bot
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content This issue or pull request belongs to the Docs Content team fix-internally Triggers a workflow to copy the issue internally and close the current issue rest Content related to rest - overview.
Projects
None yet
Development

No branches or pull requests

6 participants
@felicitymay @tonglil @docs-bot @HSUYATANG @nguyenalex836 and others