forked from 47degrees/github4s
/
Repositories.scala
348 lines (330 loc) · 13 KB
/
Repositories.scala
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
/*
* Copyright 2016-2020 47 Degrees, LLC. <http://www.47deg.com>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package github4s.algebras
import cats.data.NonEmptyList
import github4s.GithubResponses.GHResponse
import github4s.domain._
trait Repositories[F[_]] {
/**
* Get information of a particular repository
*
* @param owner of the repo
* @param repo name of the repo
* @param headers optional user headers to include in the request
* @return GHResponse[Repository] repository details
*/
def get(
owner: String,
repo: String,
headers: Map[String, String] = Map()
): F[GHResponse[Repository]]
/**
* List the repositories for a particular organization
*
* @param org organization for which we wish to retrieve the repositories
* @param `type` visibility of the retrieved repositories, can be "all", "public", "private",
* "forks", "sources" or "member"
* @param headers optional user headers to include in the request
* @return GHResponse[List[Repository]] the list of repositories for this organization
*/
def listOrgRepos(
org: String,
`type`: Option[String] = None,
pagination: Option[Pagination] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[Repository]]]
/**
* List the repositories for a particular user
*
* @param user user for which we wish to retrieve the repositories
* @param `type` visibility of the retrieved repositories, can be "all", "public", "private",
* "forks", "sources" or "member"
* @param headers optional user headers to include in the request
* @return GHResponse[List[Repository]] the list of repositories for this user
*/
def listUserRepos(
user: String,
`type`: Option[String] = None,
pagination: Option[Pagination] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[Repository]]]
/**
* Get the contents of a file or directory in a repository.
*
* The response could be a:
* - file
* - directory
* The response will be an array of objects, one object for each item in the directory.
* When listing the contents of a directory, submodules have their "type" specified as "file".
* - symlink
* If the requested :path points to a symlink, and the symlink's target is a normal file in the repository,
* then the API responds with the content of the file.
* Otherwise, the API responds with an object describing the symlink itself.
* - submodule
* The submodule_git_url identifies the location of the submodule repository,
* and the sha identifies a specific commit within the submodule repository.
* Git uses the given URL when cloning the submodule repository,
* and checks out the submodule at that specific commit.
* If the submodule repository is not hosted on github.com, the Git URLs (git_url and _links["git"])
* and the github.com URLs (html_url and _links["html"]) will have null values
*
* @param owner of the repo
* @param repo name of the repo
* @param path the content path
* @param ref the name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)
* @param headers optional user headers to include in the request
* @return GHResponse with the content defails
*/
def getContents(
owner: String,
repo: String,
path: String,
ref: Option[String] = None,
headers: Map[String, String] = Map()
): F[GHResponse[NonEmptyList[Content]]]
/**
* Creates a new file in a repository.
*
* @param owner of the repo
* @param repo name of the repo
* @param path the content path
* @param content content in bytes, as they should be written to GitHub.
* @param message the message to be included in the commit.
* @param branch the branch name (defaults to the repository's default branch)
* @param committer object containing information about the committer (filled in with authenticated user information if omitted)
* @param author object containing information about the author (filled in with committer information if omitted)
* @return GHResponse[WriteFileResponse] with details about the content created and the commit
*/
def createFile(
owner: String,
repo: String,
path: String,
message: String,
content: Array[Byte],
branch: Option[String] = None,
committer: Option[Committer] = None,
author: Option[Committer] = None,
headers: Map[String, String] = Map()
): F[GHResponse[WriteFileResponse]]
/**
* Updates an existing file in a repository.
*
* @param owner of the repo
* @param repo name of the repo
* @param path the content path
* @param message the message to be included in the commit.
* @param content the content of the file as it should be written to GitHub
* @param sha the blob sha of the file being replaced.
* @param branch the branch name (defaults to the repository's default branch)
* @param committer object containing information about the committer (filled in with authenticated user information if omitted)
* @param author object containing information about the author (filled in with committer information if omitted)
* @return GHResponse[WriteFileResponse] with details about the content updated and the commit
*/
def updateFile(
owner: String,
repo: String,
path: String,
message: String,
content: Array[Byte],
sha: String,
branch: Option[String] = None,
committer: Option[Committer] = None,
author: Option[Committer] = None,
headers: Map[String, String] = Map()
): F[GHResponse[WriteFileResponse]]
/**
* Deletes a file in a particular repo, resulting in a new commit.
*
* @param owner of the repo
* @param repo name of the repo
* @param path the content path
* @param message the message to be included in the commit.
* @param sha the blob sha of the file being replaced.
* @param branch the branch name (defaults to the repository's default branch)
* @param committer object containing information about the committer (filled in with authenticated user information if omitted)
* @param author object containing information about the author (filled in with committer information if omitted)
* @return GHResponse[WriteFileResponse] with no content and details about the commit which was added.
*/
def deleteFile(
owner: String,
repo: String,
path: String,
message: String,
sha: String,
branch: Option[String] = None,
committer: Option[Committer] = None,
author: Option[Committer] = None,
headers: Map[String, String] = Map()
): F[GHResponse[WriteFileResponse]]
/**
* Retrieve the list of commits for a particular repo
*
* @param owner of the repo
* @param repo name of the repo
* @param sha branch to start listing commits from
* @param path commits containing this file path will be returned
* @param author GitHub login or email address by which to filter by commit author.
* @param since Only commits after this date will be returned
* @param until Only commits before this date will be returned
* @param pagination Limit and Offset for pagination
* @param headers optional user headers to include in the request
* @return GHResponse[List[Commit]\] List of commit's details
*/
def listCommits(
owner: String,
repo: String,
sha: Option[String] = None,
path: Option[String] = None,
author: Option[String] = None,
since: Option[String] = None,
until: Option[String] = None,
pagination: Option[Pagination] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[Commit]]]
/**
* Retrieve list of branches for a repo
*
* @param owner of the repo
* @param repo name of the repo
* @param onlyProtected Setting to true returns only protected branches
* @param headers optional user headers to include in the request
* @return GHResponse[List[Branch]\] List of branches
*/
def listBranches(
owner: String,
repo: String,
onlyProtected: Option[Boolean] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[Branch]]]
/**
* Fetch contributors list for the the specified repository,
* sorted by the number of commits per contributor in descending order.
*
* @param owner of the repo
* @param repo name of the repo
* @param anon Set to 1 or true to include anonymous contributors in results
* @param headers optional user headers to include in the request
* @return GHResponse[List[User]\] List of contributors associated with the specified repository.
*/
def listContributors(
owner: String,
repo: String,
anon: Option[String] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[User]]]
/**
* Fetch list of collaborators for the specified repository.
* For organization-owned repositories, the list of collaborators includes outside collaborators,
* organization members that are direct collaborators, organization members with access through team memberships,
* organization members with access through default organization permissions, and organization owners.
*
* @param owner of the repo
* @param repo name of the repo
* @param affiliation Filter collaborators returned by their affiliation. Can be one of `outside`, `direct`, `all`.
* Default: `all`
* @param headers optional user headers to include in the request
* @return GHResponse[List[User]\] List of collaborators within the specified repository
*/
def listCollaborators(
owner: String,
repo: String,
affiliation: Option[String] = None,
headers: Map[String, String] = Map()
): F[GHResponse[List[User]]]
/**
* Create a new release
*
* @param owner of the repo
* @param repo name of the repo
* @param tagName the name of the tag.
* @param name the name of the release.
* @param body text describing the contents of the tag.
* @param targetCommitish specifies the commitish value that determines where the Git tag is created from.
* Can be any branch or commit SHA. Unused if the Git tag already exists.
* Default: the repository's default branch (usually `master`).
* @param draft `true` to create a draft (unpublished) release, `false` to createStatus a published one.
* Default: `false`
* @param prerelease `true` to identify the release as a prerelease.
* `false` to identify the release as a full release.
* Default: `false`
* @param headers optional user headers to include in the request
* @return a GHResponse with Release
*/
def createRelease(
owner: String,
repo: String,
tagName: String,
name: String,
body: String,
targetCommitish: Option[String] = None,
draft: Option[Boolean] = None,
prerelease: Option[Boolean] = None,
headers: Map[String, String] = Map()
): F[GHResponse[Release]]
/**
* Get the combined status for a specific ref
*
* @param owner of the repo
* @param repo name of the commit
* @param ref commit SHA, branch name or tag name
* @param headers optional user headers to include in the request
* @return a GHResponse with the combined status
*/
def getCombinedStatus(
owner: String,
repo: String,
ref: String,
headers: Map[String, String] = Map()
): F[GHResponse[CombinedStatus]]
/**
* List statuses for a commit
*
* @param owner of the repo
* @param repo name of the repo
* @param ref commit SHA, branch name or tag name
* @param headers optional user headers to include in the request
* @return a GHResponse with the status list
*/
def listStatuses(
owner: String,
repo: String,
ref: String,
headers: Map[String, String] = Map()
): F[GHResponse[List[Status]]]
/**
* Create a status
*
* @param owner of the repo
* @param repo name of the repo
* @param sha commit sha to create the status on
* @param target_url url to associate with the status, will appear in the GitHub UI
* @param state of the status: pending, success, error, or failure
* @param description of the status
* @param context identifier of the status maker
* @param headers optional user headers to include in the request
* @return a GHResopnse with the created Status
*/
def createStatus(
owner: String,
repo: String,
sha: String,
state: String,
target_url: Option[String],
description: Option[String],
context: Option[String],
headers: Map[String, String] = Map()
): F[GHResponse[Status]]
}