Source file src/github.com/xanzy/go-gitlab/group_members.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Sander van Harmelen
     3  //
     4  // Licensed under the Apache License, Version 2.0 (the "License");
     5  // you may not use this file except in compliance with the License.
     6  // You may obtain a copy of the License at
     7  //
     8  //     http://www.apache.org/licenses/LICENSE-2.0
     9  //
    10  // Unless required by applicable law or agreed to in writing, software
    11  // distributed under the License is distributed on an "AS IS" BASIS,
    12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  // See the License for the specific language governing permissions and
    14  // limitations under the License.
    15  //
    16  
    17  package gitlab
    18  
    19  import (
    20  	"fmt"
    21  	"net/http"
    22  	"time"
    23  )
    24  
    25  // GroupMembersService handles communication with the group members
    26  // related methods of the GitLab API.
    27  //
    28  // GitLab API docs: https://docs.gitlab.com/ee/api/members.html
    29  type GroupMembersService struct {
    30  	client *Client
    31  }
    32  
    33  // GroupMemberSAMLIdentity represents the SAML Identity link for the group member.
    34  //
    35  // GitLab API docs: https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
    36  // Gitlab MR for API change: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20357
    37  // Gitlab MR for API Doc change: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25652
    38  type GroupMemberSAMLIdentity struct {
    39  	ExternUID      string `json:"extern_uid"`
    40  	Provider       string `json:"provider"`
    41  	SAMLProviderID int    `json:"saml_provider_id"`
    42  }
    43  
    44  // GroupMember represents a GitLab group member.
    45  //
    46  // GitLab API docs: https://docs.gitlab.com/ee/api/members.html
    47  type GroupMember struct {
    48  	ID                int                      `json:"id"`
    49  	Username          string                   `json:"username"`
    50  	Name              string                   `json:"name"`
    51  	State             string                   `json:"state"`
    52  	AvatarURL         string                   `json:"avatar_url"`
    53  	WebURL            string                   `json:"web_url"`
    54  	CreatedAt         *time.Time               `json:"created_at"`
    55  	ExpiresAt         *ISOTime                 `json:"expires_at"`
    56  	AccessLevel       AccessLevelValue         `json:"access_level"`
    57  	Email             string                   `json:"email,omitempty"`
    58  	GroupSAMLIdentity *GroupMemberSAMLIdentity `json:"group_saml_identity"`
    59  	MemberRole        *MemberRole              `json:"member_role"`
    60  }
    61  
    62  // ListGroupMembersOptions represents the available ListGroupMembers() and
    63  // ListAllGroupMembers() options.
    64  //
    65  // GitLab API docs:
    66  // https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
    67  type ListGroupMembersOptions struct {
    68  	ListOptions
    69  	Query   *string `url:"query,omitempty" json:"query,omitempty"`
    70  	UserIDs *[]int  `url:"user_ids[],omitempty" json:"user_ids,omitempty"`
    71  }
    72  
    73  // ListGroupMembers get a list of group members viewable by the authenticated
    74  // user. Inherited members through ancestor groups are not included.
    75  //
    76  // GitLab API docs:
    77  // https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
    78  func (s *GroupsService) ListGroupMembers(gid interface{}, opt *ListGroupMembersOptions, options ...RequestOptionFunc) ([]*GroupMember, *Response, error) {
    79  	group, err := parseID(gid)
    80  	if err != nil {
    81  		return nil, nil, err
    82  	}
    83  	u := fmt.Sprintf("groups/%s/members", PathEscape(group))
    84  
    85  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
    86  	if err != nil {
    87  		return nil, nil, err
    88  	}
    89  
    90  	var gm []*GroupMember
    91  	resp, err := s.client.Do(req, &gm)
    92  	if err != nil {
    93  		return nil, resp, err
    94  	}
    95  
    96  	return gm, resp, nil
    97  }
    98  
    99  // ListAllGroupMembers get a list of group members viewable by the authenticated
   100  // user. Returns a list including inherited members through ancestor groups.
   101  //
   102  // GitLab API docs:
   103  // https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project-including-inherited-and-invited-members
   104  func (s *GroupsService) ListAllGroupMembers(gid interface{}, opt *ListGroupMembersOptions, options ...RequestOptionFunc) ([]*GroupMember, *Response, error) {
   105  	group, err := parseID(gid)
   106  	if err != nil {
   107  		return nil, nil, err
   108  	}
   109  	u := fmt.Sprintf("groups/%s/members/all", PathEscape(group))
   110  
   111  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   112  	if err != nil {
   113  		return nil, nil, err
   114  	}
   115  
   116  	var gm []*GroupMember
   117  	resp, err := s.client.Do(req, &gm)
   118  	if err != nil {
   119  		return nil, resp, err
   120  	}
   121  
   122  	return gm, resp, nil
   123  }
   124  
   125  // AddGroupMemberOptions represents the available AddGroupMember() options.
   126  //
   127  // GitLab API docs:
   128  // https://docs.gitlab.com/ee/api/members.html#add-a-member-to-a-group-or-project
   129  type AddGroupMemberOptions struct {
   130  	UserID       *int              `url:"user_id,omitempty" json:"user_id,omitempty"`
   131  	AccessLevel  *AccessLevelValue `url:"access_level,omitempty" json:"access_level,omitempty"`
   132  	ExpiresAt    *string           `url:"expires_at,omitempty" json:"expires_at"`
   133  	MemberRoleID *int              `url:"member_role_id,omitempty" json:"member_role_id,omitempty"`
   134  }
   135  
   136  // GetGroupMember gets a member of a group.
   137  //
   138  // GitLab API docs:
   139  // https://docs.gitlab.com/ee/api/members.html#get-a-member-of-a-group-or-project
   140  func (s *GroupMembersService) GetGroupMember(gid interface{}, user int, options ...RequestOptionFunc) (*GroupMember, *Response, error) {
   141  	group, err := parseID(gid)
   142  	if err != nil {
   143  		return nil, nil, err
   144  	}
   145  	u := fmt.Sprintf("groups/%s/members/%d", PathEscape(group), user)
   146  
   147  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   148  	if err != nil {
   149  		return nil, nil, err
   150  	}
   151  
   152  	gm := new(GroupMember)
   153  	resp, err := s.client.Do(req, gm)
   154  	if err != nil {
   155  		return nil, resp, err
   156  	}
   157  
   158  	return gm, resp, nil
   159  }
   160  
   161  // BillableGroupMember represents a GitLab billable group member.
   162  //
   163  // GitLab API docs: https://docs.gitlab.com/ee/api/members.html#list-all-billable-members-of-a-group
   164  type BillableGroupMember struct {
   165  	ID             int        `json:"id"`
   166  	Username       string     `json:"username"`
   167  	Name           string     `json:"name"`
   168  	State          string     `json:"state"`
   169  	AvatarURL      string     `json:"avatar_url"`
   170  	WebURL         string     `json:"web_url"`
   171  	Email          string     `json:"email"`
   172  	LastActivityOn *ISOTime   `json:"last_activity_on"`
   173  	MembershipType string     `json:"membership_type"`
   174  	Removable      bool       `json:"removable"`
   175  	CreatedAt      *time.Time `json:"created_at"`
   176  	IsLastOwner    bool       `json:"is_last_owner"`
   177  	LastLoginAt    *time.Time `json:"last_login_at"`
   178  }
   179  
   180  // ListBillableGroupMembersOptions represents the available ListBillableGroupMembers() options.
   181  //
   182  // GitLab API docs:
   183  // https://docs.gitlab.com/ee/api/members.html#list-all-billable-members-of-a-group
   184  type ListBillableGroupMembersOptions struct {
   185  	ListOptions
   186  	Search *string `url:"search,omitempty" json:"search,omitempty"`
   187  	Sort   *string `url:"sort,omitempty" json:"sort,omitempty"`
   188  }
   189  
   190  // ListBillableGroupMembers Gets a list of group members that count as billable.
   191  // The list includes members in the subgroup or subproject.
   192  //
   193  // GitLab API docs:
   194  // https://docs.gitlab.com/ee/api/members.html#list-all-billable-members-of-a-group
   195  func (s *GroupsService) ListBillableGroupMembers(gid interface{}, opt *ListBillableGroupMembersOptions, options ...RequestOptionFunc) ([]*BillableGroupMember, *Response, error) {
   196  	group, err := parseID(gid)
   197  	if err != nil {
   198  		return nil, nil, err
   199  	}
   200  	u := fmt.Sprintf("groups/%s/billable_members", PathEscape(group))
   201  
   202  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   203  	if err != nil {
   204  		return nil, nil, err
   205  	}
   206  
   207  	var bgm []*BillableGroupMember
   208  	resp, err := s.client.Do(req, &bgm)
   209  	if err != nil {
   210  		return nil, resp, err
   211  	}
   212  
   213  	return bgm, resp, nil
   214  }
   215  
   216  // RemoveBillableGroupMember removes a given group members that count as billable.
   217  //
   218  // GitLab API docs:
   219  // https://docs.gitlab.com/ee/api/members.html#remove-a-billable-member-from-a-group
   220  func (s *GroupsService) RemoveBillableGroupMember(gid interface{}, user int, options ...RequestOptionFunc) (*Response, error) {
   221  	group, err := parseID(gid)
   222  	if err != nil {
   223  		return nil, err
   224  	}
   225  	u := fmt.Sprintf("groups/%s/billable_members/%d", PathEscape(group), user)
   226  
   227  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   228  	if err != nil {
   229  		return nil, err
   230  	}
   231  
   232  	return s.client.Do(req, nil)
   233  }
   234  
   235  // AddGroupMember adds a user to the list of group members.
   236  //
   237  // GitLab API docs:
   238  // https://docs.gitlab.com/ee/api/members.html#add-a-member-to-a-group-or-project
   239  func (s *GroupMembersService) AddGroupMember(gid interface{}, opt *AddGroupMemberOptions, options ...RequestOptionFunc) (*GroupMember, *Response, error) {
   240  	group, err := parseID(gid)
   241  	if err != nil {
   242  		return nil, nil, err
   243  	}
   244  	u := fmt.Sprintf("groups/%s/members", PathEscape(group))
   245  
   246  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   247  	if err != nil {
   248  		return nil, nil, err
   249  	}
   250  
   251  	gm := new(GroupMember)
   252  	resp, err := s.client.Do(req, gm)
   253  	if err != nil {
   254  		return nil, resp, err
   255  	}
   256  
   257  	return gm, resp, nil
   258  }
   259  
   260  // ShareWithGroup shares a group with the group.
   261  //
   262  // GitLab API docs:
   263  // https://docs.gitlab.com/ee/api/groups.html#share-groups-with-groups
   264  func (s *GroupMembersService) ShareWithGroup(gid interface{}, opt *ShareWithGroupOptions, options ...RequestOptionFunc) (*Group, *Response, error) {
   265  	group, err := parseID(gid)
   266  	if err != nil {
   267  		return nil, nil, err
   268  	}
   269  	u := fmt.Sprintf("groups/%s/share", PathEscape(group))
   270  
   271  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   272  	if err != nil {
   273  		return nil, nil, err
   274  	}
   275  
   276  	g := new(Group)
   277  	resp, err := s.client.Do(req, g)
   278  	if err != nil {
   279  		return nil, resp, err
   280  	}
   281  
   282  	return g, resp, nil
   283  }
   284  
   285  // DeleteShareWithGroup allows to unshare a group from a group.
   286  //
   287  // GitLab API docs:
   288  // https://docs.gitlab.com/ee/api/groups.html#delete-link-sharing-group-with-another-group
   289  func (s *GroupMembersService) DeleteShareWithGroup(gid interface{}, groupID int, options ...RequestOptionFunc) (*Response, error) {
   290  	group, err := parseID(gid)
   291  	if err != nil {
   292  		return nil, err
   293  	}
   294  	u := fmt.Sprintf("groups/%s/share/%d", PathEscape(group), groupID)
   295  
   296  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   297  	if err != nil {
   298  		return nil, err
   299  	}
   300  
   301  	return s.client.Do(req, nil)
   302  }
   303  
   304  // EditGroupMemberOptions represents the available EditGroupMember()
   305  // options.
   306  //
   307  // GitLab API docs:
   308  // https://docs.gitlab.com/ee/api/members.html#edit-a-member-of-a-group-or-project
   309  type EditGroupMemberOptions struct {
   310  	AccessLevel  *AccessLevelValue `url:"access_level,omitempty" json:"access_level,omitempty"`
   311  	ExpiresAt    *string           `url:"expires_at,omitempty" json:"expires_at,omitempty"`
   312  	MemberRoleID *int              `url:"member_role_id,omitempty" json:"member_role_id,omitempty"`
   313  }
   314  
   315  // EditGroupMember updates a member of a group.
   316  //
   317  // GitLab API docs:
   318  // https://docs.gitlab.com/ee/api/members.html#edit-a-member-of-a-group-or-project
   319  func (s *GroupMembersService) EditGroupMember(gid interface{}, user int, opt *EditGroupMemberOptions, options ...RequestOptionFunc) (*GroupMember, *Response, error) {
   320  	group, err := parseID(gid)
   321  	if err != nil {
   322  		return nil, nil, err
   323  	}
   324  	u := fmt.Sprintf("groups/%s/members/%d", PathEscape(group), user)
   325  
   326  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   327  	if err != nil {
   328  		return nil, nil, err
   329  	}
   330  
   331  	gm := new(GroupMember)
   332  	resp, err := s.client.Do(req, gm)
   333  	if err != nil {
   334  		return nil, resp, err
   335  	}
   336  
   337  	return gm, resp, nil
   338  }
   339  
   340  // RemoveGroupMemberOptions represents the available options to remove a group member.
   341  //
   342  // GitLab API docs: https://docs.gitlab.com/ee/api/members.html#remove-a-member-from-a-group-or-project
   343  type RemoveGroupMemberOptions struct {
   344  	SkipSubresources  *bool `url:"skip_subresources,omitempty" json:"skip_subresources,omitempty"`
   345  	UnassignIssuables *bool `url:"unassign_issuables,omitempty" json:"unassign_issuables,omitempty"`
   346  }
   347  
   348  // RemoveGroupMember removes user from user team.
   349  //
   350  // GitLab API docs:
   351  // https://docs.gitlab.com/ee/api/members.html#remove-a-member-from-a-group-or-project
   352  func (s *GroupMembersService) RemoveGroupMember(gid interface{}, user int, opt *RemoveGroupMemberOptions, options ...RequestOptionFunc) (*Response, error) {
   353  	group, err := parseID(gid)
   354  	if err != nil {
   355  		return nil, err
   356  	}
   357  	u := fmt.Sprintf("groups/%s/members/%d", PathEscape(group), user)
   358  
   359  	req, err := s.client.NewRequest(http.MethodDelete, u, opt, options)
   360  	if err != nil {
   361  		return nil, err
   362  	}
   363  
   364  	return s.client.Do(req, nil)
   365  }
   366  

View as plain text