repos_collaborators.go

Documentation: github.com/google/go-github/v55/github

     1  // Copyright 2013 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  )
    12  
    13  // ListCollaboratorsOptions specifies the optional parameters to the
    14  // RepositoriesService.ListCollaborators method.
    15  type ListCollaboratorsOptions struct {
    16  	// Affiliation specifies how collaborators should be filtered by their affiliation.
    17  	// Possible values are:
    18  	//     outside - All outside collaborators of an organization-owned repository
    19  	//     direct - All collaborators with permissions to an organization-owned repository,
    20  	//              regardless of organization membership status
    21  	//     all - All collaborators the authenticated user can see
    22  	//
    23  	// Default value is "all".
    24  	Affiliation string `url:"affiliation,omitempty"`
    25  
    26  	// Permission specifies how collaborators should be filtered by the permissions they have on the repository.
    27  	// Possible values are:
    28  	// "pull", "triage", "push", "maintain", "admin"
    29  	//
    30  	// If not specified, all collaborators will be returned.
    31  	Permission string `url:"permission,omitempty"`
    32  
    33  	ListOptions
    34  }
    35  
    36  // CollaboratorInvitation represents an invitation created when adding a collaborator.
    37  // GitHub API docs: https://docs.github.com/en/rest/repos/collaborators/#response-when-a-new-invitation-is-created
    38  type CollaboratorInvitation struct {
    39  	ID          *int64      `json:"id,omitempty"`
    40  	Repo        *Repository `json:"repository,omitempty"`
    41  	Invitee     *User       `json:"invitee,omitempty"`
    42  	Inviter     *User       `json:"inviter,omitempty"`
    43  	Permissions *string     `json:"permissions,omitempty"`
    44  	CreatedAt   *Timestamp  `json:"created_at,omitempty"`
    45  	URL         *string     `json:"url,omitempty"`
    46  	HTMLURL     *string     `json:"html_url,omitempty"`
    47  }
    48  
    49  // ListCollaborators lists the GitHub users that have access to the repository.
    50  //
    51  // GitHub API docs: https://docs.github.com/en/rest/collaborators/collaborators#list-repository-collaborators
    52  func (s *RepositoriesService) ListCollaborators(ctx context.Context, owner, repo string, opts *ListCollaboratorsOptions) ([]*User, *Response, error) {
    53  	u := fmt.Sprintf("repos/%v/%v/collaborators", owner, repo)
    54  	u, err := addOptions(u, opts)
    55  	if err != nil {
    56  		return nil, nil, err
    57  	}
    58  
    59  	req, err := s.client.NewRequest("GET", u, nil)
    60  	if err != nil {
    61  		return nil, nil, err
    62  	}
    63  
    64  	var users []*User
    65  	resp, err := s.client.Do(ctx, req, &users)
    66  	if err != nil {
    67  		return nil, resp, err
    68  	}
    69  
    70  	return users, resp, nil
    71  }
    72  
    73  // IsCollaborator checks whether the specified GitHub user has collaborator
    74  // access to the given repo.
    75  // Note: This will return false if the user is not a collaborator OR the user
    76  // is not a GitHub user.
    77  //
    78  // GitHub API docs: https://docs.github.com/en/rest/collaborators/collaborators#check-if-a-user-is-a-repository-collaborator
    79  func (s *RepositoriesService) IsCollaborator(ctx context.Context, owner, repo, user string) (bool, *Response, error) {
    80  	u := fmt.Sprintf("repos/%v/%v/collaborators/%v", owner, repo, user)
    81  	req, err := s.client.NewRequest("GET", u, nil)
    82  	if err != nil {
    83  		return false, nil, err
    84  	}
    85  
    86  	resp, err := s.client.Do(ctx, req, nil)
    87  	isCollab, err := parseBoolResponse(err)
    88  	return isCollab, resp, err
    89  }
    90  
    91  // RepositoryPermissionLevel represents the permission level an organization
    92  // member has for a given repository.
    93  type RepositoryPermissionLevel struct {
    94  	// Possible values: "admin", "write", "read", "none"
    95  	Permission *string `json:"permission,omitempty"`
    96  
    97  	User *User `json:"user,omitempty"`
    98  }
    99  
   100  // GetPermissionLevel retrieves the specific permission level a collaborator has for a given repository.
   101  //
   102  // GitHub API docs: https://docs.github.com/en/rest/collaborators/collaborators#get-repository-permissions-for-a-user
   103  func (s *RepositoriesService) GetPermissionLevel(ctx context.Context, owner, repo, user string) (*RepositoryPermissionLevel, *Response, error) {
   104  	u := fmt.Sprintf("repos/%v/%v/collaborators/%v/permission", owner, repo, user)
   105  	req, err := s.client.NewRequest("GET", u, nil)
   106  	if err != nil {
   107  		return nil, nil, err
   108  	}
   109  
   110  	rpl := new(RepositoryPermissionLevel)
   111  	resp, err := s.client.Do(ctx, req, rpl)
   112  	if err != nil {
   113  		return nil, resp, err
   114  	}
   115  
   116  	return rpl, resp, nil
   117  }
   118  
   119  // RepositoryAddCollaboratorOptions specifies the optional parameters to the
   120  // RepositoriesService.AddCollaborator method.
   121  type RepositoryAddCollaboratorOptions struct {
   122  	// Permission specifies the permission to grant the user on this repository.
   123  	// Possible values are:
   124  	//     pull - team members can pull, but not push to or administer this repository
   125  	//     push - team members can pull and push, but not administer this repository
   126  	//     admin - team members can pull, push and administer this repository
   127  	//     maintain - team members can manage the repository without access to sensitive or destructive actions.
   128  	//     triage - team members can proactively manage issues and pull requests without write access.
   129  	//
   130  	// Default value is "push". This option is only valid for organization-owned repositories.
   131  	Permission string `json:"permission,omitempty"`
   132  }
   133  
   134  // AddCollaborator sends an invitation to the specified GitHub user
   135  // to become a collaborator to the given repo.
   136  //
   137  // GitHub API docs: https://docs.github.com/en/rest/collaborators/collaborators#add-a-repository-collaborator
   138  func (s *RepositoriesService) AddCollaborator(ctx context.Context, owner, repo, user string, opts *RepositoryAddCollaboratorOptions) (*CollaboratorInvitation, *Response, error) {
   139  	u := fmt.Sprintf("repos/%v/%v/collaborators/%v", owner, repo, user)
   140  	req, err := s.client.NewRequest("PUT", u, opts)
   141  	if err != nil {
   142  		return nil, nil, err
   143  	}
   144  
   145  	acr := new(CollaboratorInvitation)
   146  	resp, err := s.client.Do(ctx, req, acr)
   147  	if err != nil {
   148  		return nil, resp, err
   149  	}
   150  
   151  	return acr, resp, nil
   152  }
   153  
   154  // RemoveCollaborator removes the specified GitHub user as collaborator from the given repo.
   155  // Note: Does not return error if a valid user that is not a collaborator is removed.
   156  //
   157  // GitHub API docs: https://docs.github.com/en/rest/collaborators/collaborators#remove-a-repository-collaborator
   158  func (s *RepositoriesService) RemoveCollaborator(ctx context.Context, owner, repo, user string) (*Response, error) {
   159  	u := fmt.Sprintf("repos/%v/%v/collaborators/%v", owner, repo, user)
   160  	req, err := s.client.NewRequest("DELETE", u, nil)
   161  	if err != nil {
   162  		return nil, err
   163  	}
   164  
   165  	return s.client.Do(ctx, req, nil)
   166  }
   167
View as plain text