Debian Codegraph @

srht/buildssrht/schema.graphqls

raw
1 # This schema definition is available in the public domain, or under the terms
2 # of CC-0, at your choice.
3 scalar Time # %Y-%m-%dT%H:%M:%SZ
4 scalar Binary # base64'd string
5 scalar Cursor
6 scalar File
7
8 "Used to provide a human-friendly description of an access scope"
9 directive @scopehelp(details: String!) on ENUM_VALUE
10
11 """
12 This is used to decorate fields which are only accessible with a personal
13 access token, and are not available to clients using OAuth 2.0 access tokens.
14 """
15 directive @private on FIELD_DEFINITION
16
17 """
18 This is used to decorate fields which are for internal use, and are not
19 available to normal API users.
20 """
21 directive @internal on FIELD_DEFINITION
22
23 enum AccessScope {
24 PROFILE @scopehelp(details: "profile information")
25 JOBS @scopehelp(details: "build jobs")
26 LOGS @scopehelp(details: "build logs")
27 SECRETS @scopehelp(details: "stored secrets")
28 }
29
30 enum AccessKind {
31 RO @scopehelp(details: "read")
32 RW @scopehelp(details: "read and write")
33 }
34
35 """
36 Decorates fields for which access requires a particular OAuth 2.0 scope with
37 read or write access.
38 """
39 directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION
40
41 """
42 This used to decorate private resolvers which are only accessible to build
43 workers, and are used to facilitate the build process.
44 """
45 directive @worker on FIELD_DEFINITION
46
47 # https://semver.org
48 type Version {
49 major: Int!
50 minor: Int!
51 patch: Int!
52 buildVersion: String!
53 buildDate: String!
54
55 """
56 If this API version is scheduled for deprecation, this is the date on which
57 it will stop working; or null if this API version is not scheduled for
58 deprecation.
59 """
60 deprecationDate: Time
61
62 # Config settings
63 settings: Settings!
64 }
65
66 # Instance specific settings
67 type Settings {
68 sshUser: String!
69 buildTimeout: String!
70 }
71
72 interface Entity {
73 id: Int!
74 created: Time!
75 updated: Time!
76 """
77 The canonical name of this entity. For users, this is their username
78 prefixed with '~'. Additional entity types will be supported in the future.
79 """
80 canonicalName: String!
81 }
82
83 type User implements Entity {
84 id: Int!
85 created: Time!
86 updated: Time!
87 canonicalName: String!
88 username: String!
89 email: String!
90 url: String
91 location: String
92 bio: String
93
94 "Jobs submitted by this user."
95 jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO)
96 }
97
98 enum JobStatus {
99 PENDING
100 QUEUED
101 RUNNING
102 SUCCESS
103 FAILED
104 TIMEOUT
105 CANCELLED
106 }
107
108 enum Visibility {
109 PUBLIC
110 UNLISTED
111 PRIVATE
112 }
113
114 type Job {
115 id: Int!
116 created: Time!
117 updated: Time!
118 status: JobStatus!
119 manifest: String!
120 note: String
121 tags: [String!]!
122 visibility: Visibility!
123
124 "Name of the build image"
125 image: String!
126
127 """
128 Name of the build runner which picked up this job, or null if the job is
129 pending or queued.
130 """
131 runner: String
132
133 owner: Entity! @access(scope: PROFILE, kind: RO)
134 group: JobGroup
135 tasks: [Task!]!
136 artifacts: [Artifact!]!
137
138 "The job's top-level log file, not associated with any tasks"
139 log: Log @access(scope: LOGS, kind: RO)
140
141 "List of secrets available to this job, or null if they were disabled"
142 secrets: [Secret!] @access(scope: SECRETS, kind: RO)
143 }
144
145 type Log {
146 "The most recently written 128 KiB of the build log."
147 last128KiB: String!
148 """
149 The URL at which the full build log can be downloaded with an authenticated
150 GET request (text/plain).
151 """
152 fullURL: String!
153 }
154
155 type Artifact {
156 id: Int!
157 created: Time!
158 "Original path in the guest"
159 path: String!
160 "Size in bytes"
161 size: Int!
162 "URL at which the artifact may be downloaded, or null if pruned"
163 url: String
164 }
165
166 """
167 A cursor for enumerating a list of jobs
168
169 If there are additional results available, the cursor object may be passed
170 back into the same endpoint to retrieve another page. If the cursor is null,
171 there are no remaining results to return.
172 """
173 type JobCursor {
174 results: [Job!]!
175 cursor: Cursor
176 }
177
178 type JobGroup {
179 id: Int!
180 created: Time!
181 note: String
182 owner: Entity! @access(scope: PROFILE, kind: RO)
183 jobs: [Job!]!
184 triggers: [Trigger!]!
185 }
186
187 enum TaskStatus {
188 PENDING
189 RUNNING
190 SUCCESS
191 FAILED
192 SKIPPED
193 }
194
195 type Task {
196 id: Int!
197 created: Time!
198 updated: Time!
199 name: String!
200 status: TaskStatus!
201 log: Log @access(scope: LOGS, kind: RO)
202 job: Job!
203 }
204
205 enum TriggerCondition {
206 SUCCESS
207 FAILURE
208 ALWAYS
209 }
210
211 """
212 Triggers run upon the completion of all of the jobs in a job group. Note that
213 these triggers are distinct from the ones defined by an individual job's
214 build manifest, but are similar in functionality.
215 """
216 interface Trigger {
217 condition: TriggerCondition!
218 }
219
220 type EmailTrigger implements Trigger {
221 condition: TriggerCondition!
222 to: String!
223 cc: String
224 inReplyTo: String
225 }
226
227 type WebhookTrigger implements Trigger {
228 condition: TriggerCondition!
229 url: String!
230 }
231
232 interface Secret {
233 id: Int!
234 created: Time!
235 uuid: String!
236 name: String
237 "Set when this secret was copied from another user account"
238 fromUser: Entity
239 }
240
241 """
242 A cursor for enumerating a list of secrets
243
244 If there are additional results available, the cursor object may be passed
245 back into the same endpoint to retrieve another page. If the cursor is null,
246 there are no remaining results to return.
247 """
248 type SecretCursor {
249 results: [Secret!]!
250 cursor: Cursor
251 }
252
253 type SSHKey implements Secret {
254 id: Int!
255 created: Time!
256 uuid: String!
257 name: String
258 fromUser: Entity
259 privateKey: Binary! @worker
260 }
261
262 type PGPKey implements Secret {
263 id: Int!
264 created: Time!
265 uuid: String!
266 name: String
267 fromUser: Entity
268 privateKey: Binary! @worker
269 }
270
271 type SecretFile implements Secret {
272 id: Int!
273 created: Time!
274 uuid: String!
275 name: String
276 fromUser: Entity
277 path: String!
278 mode: Int!
279 data: Binary! @worker
280 }
281
282 type OAuthClient {
283 uuid: String!
284 }
285
286 enum WebhookEvent {
287 JOB_CREATED
288 JOB_UPDATED
289 }
290
291 interface WebhookSubscription {
292 id: Int!
293 events: [WebhookEvent!]!
294 query: String!
295 url: String!
296
297 """
298 If this webhook was registered by an authorized OAuth 2.0 client, this
299 field is non-null.
300 """
301 client: OAuthClient @private
302
303 "All deliveries which have been sent to this webhook."
304 deliveries(cursor: Cursor): WebhookDeliveryCursor!
305
306 "Returns a sample payload for this subscription, for testing purposes"
307 sample(event: WebhookEvent!): String!
308 }
309
310 type UserWebhookSubscription implements WebhookSubscription {
311 id: Int!
312 events: [WebhookEvent!]!
313 query: String!
314 url: String!
315 client: OAuthClient @private
316 deliveries(cursor: Cursor): WebhookDeliveryCursor!
317 sample(event: WebhookEvent!): String!
318 }
319
320 type WebhookDelivery {
321 uuid: String!
322 date: Time!
323 event: WebhookEvent!
324 subscription: WebhookSubscription!
325 requestBody: String!
326
327 """
328 These details are provided only after a response is received from the
329 remote server. If a response is sent whose Content-Type is not text/*, or
330 cannot be decoded as UTF-8, the response body will be null. It will be
331 truncated after 64 KiB.
332 """
333 responseBody: String
334 responseHeaders: String
335 responseStatus: Int
336 }
337
338 interface WebhookPayload {
339 uuid: String!
340 event: WebhookEvent!
341 date: Time!
342 }
343
344 type JobEvent implements WebhookPayload {
345 uuid: String!
346 event: WebhookEvent!
347 date: Time!
348
349 job: Job!
350 }
351
352 """
353 A cursor for enumerating a list of webhook deliveries
354
355 If there are additional results available, the cursor object may be passed
356 back into the same endpoint to retrieve another page. If the cursor is null,
357 there are no remaining results to return.
358 """
359 type WebhookDeliveryCursor {
360 results: [WebhookDelivery!]!
361 cursor: Cursor
362 }
363
364 """
365 A cursor for enumerating a list of webhook subscriptions
366
367 If there are additional results available, the cursor object may be passed
368 back into the same endpoint to retrieve another page. If the cursor is null,
369 there are no remaining results to return.
370 """
371 type WebhookSubscriptionCursor {
372 results: [WebhookSubscription!]!
373 cursor: Cursor
374 }
375
376 type Query {
377 "Returns API version information."
378 version: Version!
379
380 "Returns the authenticated user."
381 me: User! @access(scope: PROFILE, kind: RO)
382
383 "Returns a specific user."
384 userByID(id: Int!): User @access(scope: PROFILE, kind: RO)
385 userByName(username: String!): User @access(scope: PROFILE, kind: RO)
386
387 "Returns jobs submitted by the authenticated user."
388 jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO)
389
390 "Returns information about a specific job."
391 job(id: Int!): Job @access(scope: JOBS, kind: RO)
392
393 "Returns secrets owned by the authenticated user."
394 secrets(cursor: Cursor): SecretCursor! @access(scope: SECRETS, kind: RO)
395
396 """
397 Returns a list of user webhook subscriptions. For clients
398 authenticated with a personal access token, this returns all webhooks
399 configured by all GraphQL clients for your account. For clients
400 authenticated with an OAuth 2.0 access token, this returns only webhooks
401 registered for your client.
402 """
403 userWebhooks(cursor: Cursor): WebhookSubscriptionCursor!
404
405 "Returns details of a user webhook subscription by its ID."
406 userWebhook(id: Int!): WebhookSubscription
407
408 """
409 Returns information about the webhook currently being processed. This is
410 not valid during normal queries over HTTP, and will return an error if used
411 outside of a webhook context.
412 """
413 webhook: WebhookPayload!
414 }
415
416 enum TriggerType {
417 EMAIL
418 WEBHOOK
419 }
420
421 input EmailTriggerInput {
422 to: String!
423 cc: String
424 inReplyTo: String
425 }
426
427 input WebhookTriggerInput {
428 url: String!
429 }
430
431 input TriggerInput {
432 type: TriggerType!
433 condition: TriggerCondition!
434 email: EmailTriggerInput
435 webhook: WebhookTriggerInput
436 }
437
438 input UserWebhookInput {
439 url: String!
440 events: [WebhookEvent!]!
441 query: String!
442 }
443
444 type Mutation {
445 """
446 Submits a new job to the queue.
447
448 'secrets' may be set to false to disable secrets for this build. If
449 unspecified, secrets are enabled if at least one is specified in the manifest
450 and the SECRETS:RO grant is available. Enabling secrets requires the
451 SECRETS:RO grant.
452
453 'execute' may be set to false to defer queueing this job. Builds are
454 executed immediately if unspecified.
455 """
456 submit(manifest: String!, tags: [String!] note: String, secrets: Boolean,
457 execute: Boolean, visibility: Visibility): Job! @access(scope: JOBS, kind: RW)
458
459 "Queues a pending job."
460 start(jobID: Int!): Job @access(scope: JOBS, kind: RW)
461
462 "Cancels a submitted job."
463 cancel(jobId: Int!): Job @access(scope: JOBS, kind: RW)
464
465 "Updates the visibility and tags of a job."
466 update(jobId: Int!, visibility: Visibility!, tags: [String!]): Job @access(scope: JOBS, kind: RW)
467
468 """
469 Creates a job group from several pending jobs.
470
471 'execute' may be set to false to defer queueing this job. The job group is
472 executed immediately if unspecified.
473 """
474 createGroup(jobIds: [Int!]! triggers: [TriggerInput!],
475 execute: Boolean, note: String): JobGroup! @access(scope: JOBS, kind: RW)
476
477 "Starts a pending job group."
478 startGroup(groupId: Int!): JobGroup @access(scope: JOBS, kind: RW)
479
480 "Copies a secret to the target user account."
481 shareSecret(uuid: String!, user: String!): Secret! @access(scope: SECRETS, kind: RW)
482
483 ###
484 ### The following resolvers are for internal worker use
485
486 "Claims a job."
487 claim(jobId: Int!): Job @worker
488
489 "Updates job status."
490 updateJob(jobId: Int!, status: JobStatus!): Job @worker
491
492 "Updates task status."
493 updateTask(taskId: Int!, status: TaskStatus!): Job @worker
494
495 "Uploads a build artifact."
496 createArtifact(jobId: Int!, path: String!, contents: File!): Artifact @worker
497
498 """
499 Creates a new user webhook subscription. When an event from the
500 provided list of events occurs, the 'query' parameter (a GraphQL query)
501 will be evaluated and the results will be sent to the provided URL as the
502 body of an HTTP POST request. The list of events must include at least one
503 event, and no duplicates.
504
505 This query is evaluated in the webhook context, such that query { webhook }
506 may be used to access details of the event which trigged the webhook. The
507 query may not make any mutations.
508 """
509 createUserWebhook(config: UserWebhookInput!): WebhookSubscription!
510
511 """
512 Deletes a user webhook. Any events already queued may still be
513 delivered after this request completes. Clients authenticated with a
514 personal access token may delete any webhook registered for their account,
515 but authorized OAuth 2.0 clients may only delete their own webhooks.
516 Manually deleting a webhook configured by a third-party client may cause
517 unexpected behavior with the third-party integration.
518 """
519 deleteUserWebhook(id: Int!): WebhookSubscription!
520
521 """
522 Deletes the authenticated user's account. Internal use only.
523 """
524 deleteUser: Int! @internal
525 }