Overview

Collaborators are the users invited by the owner to help in software development. The read and write permissions mean that the collaborators can pull the contents of the repository, make the required changes, and push the content back. A repository owner sends a collaboration invite to the user they wish to collaborate with. This invite needs to be accepted within seven days, after which it expires. There’s no limit to the number of collaborators that can be added to a specific repository.

List the collaborators of the repository

The authenticated users with the push access can use this endpoint. Authentication can be done by providing the access token. The list of collaborators includes all the members who have access to the repository with the default permissions.

The code below retrieves the list of collaborators of a repository:

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/collaborators'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Check if a user is a collaborator of the repository

Any authenticated user who has a direct or indirect collaboration with a repository is included in the list of collaborators. The code below checks whether or not a particular user is a collaborator of a repository. We need to specify the username of the user to be checked, in the place of <username> in the URL. We can see this in line 6.

The HTTP response codes returned are as follows:

  • 204: The user is the collaborator of the repository.
  • 404: The user is not the collaborator of the repository.
Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/collaborators/<username>'
response = requests.get(url, headers=headers)
if response.status_code == 204:
    print('The user is a collaborator')
else:
    print('The user is not a collaborator')

Add a collaborator to the repository

A collaborator can be added to a repository with certain permissions. These permissions can be:

  • pull: This allows the collaborator to only pull the repository.
  • push: This allows the collaborator to only push the repository.
  • admin: This allows the collaborator to pull, push, and administer.
  • maintain: This permission is for managers to manage repositories without access to sensitive data.
  • triage: This is for contributors to manage pull requests without the write access.

All these permissions are valid for organization-owned repositories. However, when we add a collaborator to an organization repository, we need to see that the permission is equal to or higher than the permission of the base org permission.

Let's run the code below to add a collaborator to our repository. Specify the username of the collaborator in the place of <username> in the URL. We can see this in line 6.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/collaborators/<username>'
data = json.dumps({
    'permission': '<permission>'
})
response = requests.put(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=4))

Remove a collaborator from a repository

Now that we’ve practiced adding a collaborator to our repository, let’s try removing one. Don't forget to specify the username of the collaborator to be removed in the place of <username> in the URL. We can see this in line 6.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/collaborators/<username>'
response = requests.delete(url, headers=headers)
print(response)

Get the permission of a repository’s user

The following code gets the permissions of the user of a repository. As usual, the <username> in the URL specifies the user whose permissions we want to get.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/collaborators/<username>/permission'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))