`omitempty` tag on `InstallationAccessTokenOptions.Repositories` masking functionality of GitHub API about go-github HOT 11 OPEN

So the documentation doesn't actually specify this behavior but basically you can have the endpoint return the list of all accessible repositories in the installation by specifying an empty array for the repositories parameter. It saved a round trip to the separate endpoint.

Command with empty array

curl -s "https://api.github.com/app/installations/$APP_INSTALL_ID/access_tokens" \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $APP_JWT" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -d '{"repositories":[],"permissions":{"contents":"read"}}' 

Output

{
  "token": "<token>",
  "expires_at": "2024-03-17T02:30:32Z",
  "permissions": {
    "contents": "read",
    "metadata": "read"
  },
  "repositories": ["<all repos in installation...>"],
  "repository_selection": "all"
}

Command with null or no repositories

curl -s "https://api.github.com/app/installations/$APP_INSTALL_ID/access_tokens" \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $APP_JWT" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -d '{"repositories":null,"permissions":{"contents":"read"}}'
# OR
curl -s "https://api.github.com/app/installations/$APP_INSTALL_ID/access_tokens" \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $APP_JWT" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -d '{"permissions":{"contents":"read"}}'

Output

{
  "token": "<token>",
  "expires_at": "2024-03-17T02:30:32Z",
  "permissions": {
    "contents": "read",
    "metadata": "read"
  },
  "repository_selection": "all"
}

from go-github.

According to the official docs:

Optionally, you can use the repositories or repository_ids body parameters to specify individual repositories that the installation access token can access. If you don't use repositories or repository_ids to grant access to specific repositories, the installation access token will have access to all repositories that the installation was granted access to. The installation access token cannot be granted access to repositories that the installation was not granted access to. Up to 500 repositories can be listed in this manner.

so these fields are optional, hence the omitempty, and it's not clear (to me) what the behavior is if you were to send it an empty array (as opposed to not sending the field at all, which omitempty does).

You didn't state what you are trying to do by providing it an empty array.

Are you trying to remove access to all repositories? If so, I'm wondering if that might be a different endpoint, such as this one?

If you are trying to do something else, then I need to warn you against removing omitempty from optional body parameters, as that has historically wreaked havoc with other uses of the endpoint, and we've had to create additional endpoints to address the other behavior.

So please clarify what you are trying to do, and if you would like to create a PR to address the issue.

Thanks.

from go-github.

Awesome... Thank you for the detailed example!

Then I'm thinking we need to have a new, separate endpoint that handles this special case... with a name that makes the distinction clear.
What do you think?

Do you want to write it, @gillisandrew ?

from go-github.