Okay, so this turns out to be an API documentation issue because: https://developer.github.com/v3/repos/collaborators/#add-user-as-a-collaborator

Nowhere in the docs here is it mentioned that this endpoint can also update the permissions on existing collaborators, although it is mentioned in the Octokit library docs: https://github.com/octokit/octokit.rb/blob/14bb1a1d4fec8d2250dc6f6b9cb2d446a0332d58/lib/octokit/client/repositories.rb#L337

But, even more confusingly, the given permission levels do not match the levels shown on the GitHub website. There are actually five permission levels, not three: Read, Triage, Write, Maintain, Admin.

Even worse , when hitting the endpoint using the permissions “Triage”, “Maintain” or “Admin”, they successfully modify the existing collaborator permissions. But, when using what you would might expect to work (“Read” or “Write”) it will fail. You need to use the permissions “Pull” (which is read-only access or “Read” permissions on the website) or “Push” (which is “Write” permissions on the website) for this to work properly.

So either the permission names on the GitHub website need to be changed, or the documentation for the API needs to updated to explain that:

1. the add user as a collaborator endpoint can actually update the permission of existing users and
2. the actual permission levels allowed are: Pull (which is Read), Triage, Push (which is Write), Maintain, Admin

Though, it would be really awesome to allow “Read” and “Write” on this endpoint as alises for the currently established names (according to the API anyways) to maybe save someone down the line a huge, hours-long headache.