1//
2// Copyright 2017, 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
17package gitlab
18
19import (
20 "fmt"
21)
22
23// GroupsService handles communication with the group related methods of
24// the GitLab API.
25//
26// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html
27type GroupsService struct {
28 client *Client
29}
30
31// Group represents a GitLab group.
32//
33// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html
34type Group struct {
35 ID int `json:"id"`
36 Name string `json:"name"`
37 Path string `json:"path"`
38 Description string `json:"description"`
39 Visibility *VisibilityValue `json:"visibility"`
40 LFSEnabled bool `json:"lfs_enabled"`
41 AvatarURL string `json:"avatar_url"`
42 WebURL string `json:"web_url"`
43 RequestAccessEnabled bool `json:"request_access_enabled"`
44 FullName string `json:"full_name"`
45 FullPath string `json:"full_path"`
46 ParentID int `json:"parent_id"`
47 Projects []*Project `json:"projects"`
48 Statistics *StorageStatistics `json:"statistics"`
49 CustomAttributes []*CustomAttribute `json:"custom_attributes"`
50}
51
52// ListGroupsOptions represents the available ListGroups() options.
53//
54// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#list-project-groups
55type ListGroupsOptions struct {
56 ListOptions
57 AllAvailable *bool `url:"all_available,omitempty" json:"all_available,omitempty"`
58 MinAccessLevel *AccessLevelValue `url:"min_access_level,omitempty" json:"min_access_level,omitempty"`
59 OrderBy *string `url:"order_by,omitempty" json:"order_by,omitempty"`
60 Owned *bool `url:"owned,omitempty" json:"owned,omitempty"`
61 Search *string `url:"search,omitempty" json:"search,omitempty"`
62 SkipGroups []int `url:"skip_groups,omitempty" json:"skip_groups,omitempty"`
63 Sort *string `url:"sort,omitempty" json:"sort,omitempty"`
64 Statistics *bool `url:"statistics,omitempty" json:"statistics,omitempty"`
65 WithCustomAttributes *bool `url:"with_custom_attributes,omitempty" json:"with_custom_attributes,omitempty"`
66}
67
68// ListGroups gets a list of groups (as user: my groups, as admin: all groups).
69//
70// GitLab API docs:
71// https://docs.gitlab.com/ce/api/groups.html#list-project-groups
72func (s *GroupsService) ListGroups(opt *ListGroupsOptions, options ...OptionFunc) ([]*Group, *Response, error) {
73 req, err := s.client.NewRequest("GET", "groups", opt, options)
74 if err != nil {
75 return nil, nil, err
76 }
77
78 var g []*Group
79 resp, err := s.client.Do(req, &g)
80 if err != nil {
81 return nil, resp, err
82 }
83
84 return g, resp, err
85}
86
87// GetGroup gets all details of a group.
88//
89// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#details-of-a-group
90func (s *GroupsService) GetGroup(gid interface{}, options ...OptionFunc) (*Group, *Response, error) {
91 group, err := parseID(gid)
92 if err != nil {
93 return nil, nil, err
94 }
95 u := fmt.Sprintf("groups/%s", pathEscape(group))
96
97 req, err := s.client.NewRequest("GET", u, nil, options)
98 if err != nil {
99 return nil, nil, err
100 }
101
102 g := new(Group)
103 resp, err := s.client.Do(req, g)
104 if err != nil {
105 return nil, resp, err
106 }
107
108 return g, resp, err
109}
110
111// CreateGroupOptions represents the available CreateGroup() options.
112//
113// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#new-group
114type CreateGroupOptions struct {
115 Name *string `url:"name,omitempty" json:"name,omitempty"`
116 Path *string `url:"path,omitempty" json:"path,omitempty"`
117 Description *string `url:"description,omitempty" json:"description,omitempty"`
118 Visibility *VisibilityValue `url:"visibility,omitempty" json:"visibility,omitempty"`
119 LFSEnabled *bool `url:"lfs_enabled,omitempty" json:"lfs_enabled,omitempty"`
120 RequestAccessEnabled *bool `url:"request_access_enabled,omitempty" json:"request_access_enabled,omitempty"`
121 ParentID *int `url:"parent_id,omitempty" json:"parent_id,omitempty"`
122}
123
124// CreateGroup creates a new project group. Available only for users who can
125// create groups.
126//
127// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#new-group
128func (s *GroupsService) CreateGroup(opt *CreateGroupOptions, options ...OptionFunc) (*Group, *Response, error) {
129 req, err := s.client.NewRequest("POST", "groups", opt, options)
130 if err != nil {
131 return nil, nil, err
132 }
133
134 g := new(Group)
135 resp, err := s.client.Do(req, g)
136 if err != nil {
137 return nil, resp, err
138 }
139
140 return g, resp, err
141}
142
143// TransferGroup transfers a project to the Group namespace. Available only
144// for admin.
145//
146// GitLab API docs:
147// https://docs.gitlab.com/ce/api/groups.html#transfer-project-to-group
148func (s *GroupsService) TransferGroup(gid interface{}, pid interface{}, options ...OptionFunc) (*Group, *Response, error) {
149 group, err := parseID(gid)
150 if err != nil {
151 return nil, nil, err
152 }
153 project, err := parseID(pid)
154 if err != nil {
155 return nil, nil, err
156 }
157 u := fmt.Sprintf("groups/%s/projects/%s", pathEscape(group), pathEscape(project))
158
159 req, err := s.client.NewRequest("POST", u, nil, options)
160 if err != nil {
161 return nil, nil, err
162 }
163
164 g := new(Group)
165 resp, err := s.client.Do(req, g)
166 if err != nil {
167 return nil, resp, err
168 }
169
170 return g, resp, err
171}
172
173// UpdateGroupOptions represents the set of available options to update a Group;
174// as of today these are exactly the same available when creating a new Group.
175//
176// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#update-group
177type UpdateGroupOptions CreateGroupOptions
178
179// UpdateGroup updates an existing group; only available to group owners and
180// administrators.
181//
182// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#update-group
183func (s *GroupsService) UpdateGroup(gid interface{}, opt *UpdateGroupOptions, options ...OptionFunc) (*Group, *Response, error) {
184 group, err := parseID(gid)
185 if err != nil {
186 return nil, nil, err
187 }
188 u := fmt.Sprintf("groups/%s", pathEscape(group))
189
190 req, err := s.client.NewRequest("PUT", u, opt, options)
191 if err != nil {
192 return nil, nil, err
193 }
194
195 g := new(Group)
196 resp, err := s.client.Do(req, g)
197 if err != nil {
198 return nil, resp, err
199 }
200
201 return g, resp, err
202}
203
204// DeleteGroup removes group with all projects inside.
205//
206// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#remove-group
207func (s *GroupsService) DeleteGroup(gid interface{}, options ...OptionFunc) (*Response, error) {
208 group, err := parseID(gid)
209 if err != nil {
210 return nil, err
211 }
212 u := fmt.Sprintf("groups/%s", pathEscape(group))
213
214 req, err := s.client.NewRequest("DELETE", u, nil, options)
215 if err != nil {
216 return nil, err
217 }
218
219 return s.client.Do(req, nil)
220}
221
222// SearchGroup get all groups that match your string in their name or path.
223//
224// GitLab API docs: https://docs.gitlab.com/ce/api/groups.html#search-for-group
225func (s *GroupsService) SearchGroup(query string, options ...OptionFunc) ([]*Group, *Response, error) {
226 var q struct {
227 Search string `url:"search,omitempty" json:"search,omitempty"`
228 }
229 q.Search = query
230
231 req, err := s.client.NewRequest("GET", "groups", &q, options)
232 if err != nil {
233 return nil, nil, err
234 }
235
236 var g []*Group
237 resp, err := s.client.Do(req, &g)
238 if err != nil {
239 return nil, resp, err
240 }
241
242 return g, resp, err
243}
244
245// ListGroupProjectsOptions represents the available ListGroupProjects()
246// options.
247//
248// GitLab API docs:
249// https://docs.gitlab.com/ce/api/groups.html#list-a-group-39-s-projects
250type ListGroupProjectsOptions struct {
251 ListOptions
252 Archived *bool `url:"archived,omitempty" json:"archived,omitempty"`
253 Visibility *VisibilityValue `url:"visibility,omitempty" json:"visibility,omitempty"`
254 OrderBy *string `url:"order_by,omitempty" json:"order_by,omitempty"`
255 Sort *string `url:"sort,omitempty" json:"sort,omitempty"`
256 Search *string `url:"search,omitempty" json:"search,omitempty"`
257 Simple *bool `url:"simple,omitempty" json:"simple,omitempty"`
258 Owned *bool `url:"owned,omitempty" json:"owned,omitempty"`
259 Starred *bool `url:"starred,omitempty" json:"starred,omitempty"`
260 WithIssuesEnabled *bool `url:"with_issues_enabled,omitempty" json:"with_issues_enabled,omitempty"`
261 WithMergeRequestsEnabled *bool `url:"with_merge_requests_enabled,omitempty" json:"with_merge_requests_enabled,omitempty"`
262 WithShared *bool `url:"with_shared,omitempty" json:"with_shared,omitempty"`
263 IncludeSubgroups *bool `url:"include_subgroups,omitempty" json:"include_subgroups,omitempty"`
264 WithCustomAttributes *bool `url:"with_custom_attributes,omitempty" json:"with_custom_attributes,omitempty"`
265}
266
267// ListGroupProjects get a list of group projects
268//
269// GitLab API docs:
270// https://docs.gitlab.com/ce/api/groups.html#list-a-group-39-s-projects
271func (s *GroupsService) ListGroupProjects(gid interface{}, opt *ListGroupProjectsOptions, options ...OptionFunc) ([]*Project, *Response, error) {
272 group, err := parseID(gid)
273 if err != nil {
274 return nil, nil, err
275 }
276 u := fmt.Sprintf("groups/%s/projects", pathEscape(group))
277
278 req, err := s.client.NewRequest("GET", u, opt, options)
279 if err != nil {
280 return nil, nil, err
281 }
282
283 var p []*Project
284 resp, err := s.client.Do(req, &p)
285 if err != nil {
286 return nil, resp, err
287 }
288
289 return p, resp, err
290}
291
292// ListSubgroupsOptions represents the available ListSubgroupsOptions()
293// options.
294//
295// GitLab API docs:
296// https://docs.gitlab.com/ce/api/groups.html#list-a-groups-s-subgroups
297type ListSubgroupsOptions ListGroupsOptions
298
299// ListSubgroups gets a list of subgroups for a given project.
300//
301// GitLab API docs:
302// https://docs.gitlab.com/ce/api/groups.html#list-a-groups-s-subgroups
303func (s *GroupsService) ListSubgroups(gid interface{}, opt *ListSubgroupsOptions, options ...OptionFunc) ([]*Group, *Response, error) {
304 group, err := parseID(gid)
305 if err != nil {
306 return nil, nil, err
307 }
308 u := fmt.Sprintf("groups/%s/subgroups", pathEscape(group))
309
310 req, err := s.client.NewRequest("GET", u, opt, options)
311 if err != nil {
312 return nil, nil, err
313 }
314
315 var g []*Group
316 resp, err := s.client.Do(req, &g)
317 if err != nil {
318 return nil, resp, err
319 }
320
321 return g, resp, err
322}