Answer two questions before anything that depends on identity: who is acting, and what
that account can actually see or change.
get_me returns the authenticated user. Its loginis the value every later question is asked in terms of — "my pull requests", "issues
assigned to me", "repositories I can push to" all mean that login.
get_teams. Called with no argument itreturns the teams the authenticated account belongs to; pass user to ask the same
about someone else, which only works for organisations the current credentials can
already see.
get_team_members, using the organisation asorg and the team's team_slug. The slug is the hyphenated form from the team's
address, not its display name.
list_repository_collaborators. Useaffiliation to separate the populations: direct for people granted access on the
repository itself, outside for collaborators who are not organisation members, andall for the combined view. The distinction matters because all includes people
whose access comes from a team, who are invisible under direct.
search_users when you have a person and needtheir login. Qualify the query — a bare personal name matches widely.
bounded by its credentials, and a report that does not say so reads as complete.
reviews, repositories I maintain — depends on login. Resolve it rather than
inferring it from a repository owner or from earlier conversation.
given repository; the team may have no grant there. Check access where access
matters.
get_teams may notexist, or may simply be invisible to these credentials. Both are limited to
organisations the current credentials reach, and neither can tell you which case you
are in.
login does not.When a request names a person, resolve to a login before acting on it, and say
which account you resolved to.
login — the only durable identifier for an account. Report it alongside a displayname whenever the two differ.
type — distinguishes a user from an organisation. A great deal of confusion comesfrom treating an organisation as a person.
team_slug versus a team's display name — only the slug addresses a team.affiliation — direct and all answer different questions, and quoting one as theother overstates or understates who can change the repository.
nextPage — collaborator results are paginated. A large organisation's list is notthe first page, and treating it as the whole set produces a confidently wrong answer
about who has access.
Nothing here changes anything: all five are read-only. The care needed is about what is
done with the answer rather than about the calls themselves.
the lookup returns more than one plausible account, ask which — do not pick the
closest match and go on to assign, request, or mention them.
a roster of an organisation because a lookup made it easy is not part of the task,
and should be agreed before it is produced.
token, its scopes, or anything else about how access was obtained.
exactly that. It is not the same as "the account belongs to no teams".
from the team's address rather than guessing a hyphenation.
repository. Report that the access question could not be answered, rather than
reporting an empty list, which reads as "nobody has access".
may have been renamed, or it may not exist. Say which you could not distinguish, and
ask for a login.
to tell them apart and ask.