BlueGit

timfa bluegit

Files

bluegit / internal / webhook / openapi.go

openapi.go

openapi.go 23.6 KiB Download Raw
1package webhook
2
3import "encoding/json"
4
5// OpenAPI beschrijft de JSON-body die een webhook ontvangt.
6func OpenAPI() []byte {
7 obj := func(desc string, props map[string]any, required []string) map[string]any {
8 return map[string]any{
9 "type": "object", "description": desc,
10 "properties": props, "required": required,
11 }
12 }
13 str := func(desc string) map[string]any {
14 return map[string]any{"type": "string", "description": desc}
15 }
16 num := func(desc string) map[string]any {
17 return map[string]any{"type": "number", "description": desc}
18 }
19 boolean := func(desc string) map[string]any {
20 return map[string]any{"type": "boolean", "description": desc}
21 }
22 post := func(summary, ref string) map[string]any {
23 return map[string]any{
24 "post": map[string]any{
25 "summary": summary,
26 "requestBody": map[string]any{
27 "required": true,
28 "content": map[string]any{
29 "application/json": map[string]any{
30 "schema": map[string]any{"$ref": ref},
31 },
32 },
33 },
34 "responses": map[string]any{"200": map[string]any{"description": "The receiver accepted the event."}},
35 },
36 }
37 }
38 doc := map[string]any{
39 "openapi": "3.1.0",
40 "info": map[string]any{
41 "title": "BlueGit webhook payloads",
42 "version": "1",
43 "description": "JSON body of a BlueGit webhook when the body template is empty. " +
44 "pipeline_success and pipeline_failure include the pipeline and every job. " +
45 "Every job includes its console output: the last 200 lines, at most 64 KiB. Secret values of at least 8 characters are replaced with [MASKED]. " +
46 "log_truncated is true when the log was cut. log_url is then GET /api/v1/repos/{owner}/{repo}/jobs/{id}/log and needs Authorization Bearer with a personal token that can read the repo. " +
47 "A push lists ref, before, after and up to 20 commits. Each commit has sha, message, author, timestamp, URL, changed files and diff_url. A file has status added, modified, removed or renamed, plus added and deleted line counts. The payload does not include the diff text. " +
48 "diff_url for a commit is GET /api/v1/repos/{owner}/{repo}/commits/{sha}/diff. " +
49 "A merge request includes reviewers, comments, up to 20 commits, diff statistics and diff_url, and no diff text. " +
50 "diff_url for a merge request is GET /api/v1/repos/{owner}/{repo}/merge-requests/{id}/diff. " +
51 "Both diff requests need Authorization Bearer and a personal token that can read the repo. " +
52 "A merge request uses action opened, merged or commented, and commented includes the comment text. " +
53 "A release lists the tag, name, commit and asset URLs. " +
54 "An issue event has object_kind issue and action opened, updated, closed, reopened or commented. " +
55 "It includes the issue number, title, description, status, confidential flag, author, assignees, labels, milestone and due date. " +
56 "A commented action also includes the comment text.",
57 },
58 "servers": []any{map[string]any{"url": "/api/v1"}},
59 "paths": map[string]any{
60 "/repos/{owner}/{repo}/commits/{sha}/diff": map[string]any{
61 "get": map[string]any{
62 "summary": "Commit diff",
63 "description": "Returns the unified diff of the commit against its first parent as text/plain. A root commit is compared with an empty tree. Requires a personal access token that can read the repo. On a public repo any valid personal token is enough. Job tokens are rejected.",
64 "security": []any{map[string]any{"bearer": []any{}}},
65 "parameters": []any{
66 map[string]any{"name": "owner", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
67 map[string]any{"name": "repo", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
68 map[string]any{"name": "sha", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
69 },
70 "responses": map[string]any{
71 "200": map[string]any{
72 "description": "Unified diff.",
73 "content": map[string]any{"text/plain": map[string]any{"schema": map[string]any{"type": "string"}}},
74 },
75 "401": map[string]any{"description": "Missing or invalid token."},
76 "403": map[string]any{"description": "The token cannot read this private repo."},
77 "404": map[string]any{"description": "Unknown repo or commit."},
78 },
79 },
80 },
81 "/repos/{owner}/{repo}/merge-requests/{id}/diff": map[string]any{
82 "get": map[string]any{
83 "summary": "Merge request diff",
84 "description": "Returns the three-dot unified diff from the target branch to the source branch as text/plain. Requires a personal access token that can read the repo. On a public repo any valid personal token is enough. Job tokens are rejected.",
85 "security": []any{map[string]any{"bearer": []any{}}},
86 "parameters": []any{
87 map[string]any{"name": "owner", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
88 map[string]any{"name": "repo", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
89 map[string]any{"name": "id", "in": "path", "required": true, "schema": map[string]any{"type": "integer"}},
90 },
91 "responses": map[string]any{
92 "200": map[string]any{
93 "description": "Unified diff.",
94 "content": map[string]any{"text/plain": map[string]any{"schema": map[string]any{"type": "string"}}},
95 },
96 "401": map[string]any{"description": "Missing or invalid token."},
97 "403": map[string]any{"description": "The token cannot read this private repo."},
98 "404": map[string]any{"description": "Unknown repo or merge request."},
99 },
100 },
101 },
102 "/repos/{owner}/{repo}/jobs/{id}/log": map[string]any{
103 "get": map[string]any{
104 "summary": "Full job log",
105 "description": "Returns the full console output as text/plain. Secret values of at least 8 characters are replaced with [MASKED]. Requires a personal access token. A token that can read the repo is enough, and on a public repo any valid personal token is enough. Job tokens are rejected.",
106 "security": []any{map[string]any{"bearer": []any{}}},
107 "parameters": []any{
108 map[string]any{"name": "owner", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
109 map[string]any{"name": "repo", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
110 map[string]any{"name": "id", "in": "path", "required": true, "schema": map[string]any{"type": "integer"}},
111 },
112 "responses": map[string]any{
113 "200": map[string]any{
114 "description": "Full log.",
115 "content": map[string]any{"text/plain": map[string]any{"schema": map[string]any{"type": "string"}}},
116 },
117 "401": map[string]any{"description": "Missing or invalid token."},
118 "403": map[string]any{"description": "The token cannot read this private repo."},
119 "404": map[string]any{"description": "Unknown repo or job."},
120 },
121 },
122 },
123 "/repos/{owner}/{repo}/issues": map[string]any{
124 "get": map[string]any{
125 "summary": "List issues",
126 "description": "Lists issues. Query state is open, closed or all. Query q searches title and description. Query label and assignee filter. Confidential issues of other people are omitted unless the token is Reporter or higher. A personal token is required. On a public repo any valid personal token can read. Job tokens are rejected.",
127 "security": []any{map[string]any{"bearer": []any{}}},
128 "parameters": []any{
129 map[string]any{"name": "owner", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
130 map[string]any{"name": "repo", "in": "path", "required": true, "schema": map[string]any{"type": "string"}},
131 map[string]any{"name": "state", "in": "query", "schema": map[string]any{"type": "string"}},
132 map[string]any{"name": "q", "in": "query", "schema": map[string]any{"type": "string"}},
133 map[string]any{"name": "label", "in": "query", "schema": map[string]any{"type": "string"}},
134 map[string]any{"name": "assignee", "in": "query", "schema": map[string]any{"type": "string"}},
135 },
136 "responses": map[string]any{
137 "200": map[string]any{"description": "Issue list."},
138 "401": map[string]any{"description": "Missing or invalid token."},
139 "403": map[string]any{"description": "The token cannot read this private repo."},
140 },
141 },
142 "post": map[string]any{
143 "summary": "Create an issue",
144 "description": "Creates an issue. Title is required. Readonly may set confidential. Labels, assignees, milestone and due_date need Reporter or higher. A label or milestone must already exist.",
145 "security": []any{map[string]any{"bearer": []any{}}},
146 "responses": map[string]any{
147 "201": map[string]any{"description": "Created issue."},
148 "401": map[string]any{"description": "Missing or invalid token."},
149 "403": map[string]any{"description": "The token cannot create an issue, or it sent triage fields without Reporter."},
150 },
151 },
152 },
153 "/repos/{owner}/{repo}/issues/{number}": map[string]any{
154 "get": map[string]any{
155 "summary": "Read an issue",
156 "description": "Returns one issue and its comments. A confidential issue is 404 unless the token belongs to the author or a Reporter.",
157 "security": []any{map[string]any{"bearer": []any{}}},
158 "responses": map[string]any{
159 "200": map[string]any{"description": "The issue."},
160 "401": map[string]any{"description": "Missing or invalid token."},
161 "404": map[string]any{"description": "Unknown issue, or a confidential issue you cannot see."},
162 },
163 },
164 "put": map[string]any{
165 "summary": "Update an issue",
166 "description": "Omitted fields stay as they are. The author may change title, description and state. Labels, assignees, milestone, due_date and confidential need Reporter. State is open or closed.",
167 "security": []any{map[string]any{"bearer": []any{}}},
168 "responses": map[string]any{
169 "200": map[string]any{"description": "Updated issue."},
170 "401": map[string]any{"description": "Missing or invalid token."},
171 "403": map[string]any{"description": "The token cannot change this field."},
172 },
173 },
174 },
175 "/repos/{owner}/{repo}/issues/{number}/notes": map[string]any{
176 "post": map[string]any{
177 "summary": "Comment on an issue",
178 "description": "Adds a comment. Readonly is enough. Sends an issue webhook with action commented.",
179 "security": []any{map[string]any{"bearer": []any{}}},
180 "responses": map[string]any{
181 "201": map[string]any{"description": "Created comment."},
182 "401": map[string]any{"description": "Missing or invalid token."},
183 "403": map[string]any{"description": "The token cannot comment."},
184 },
185 },
186 },
187 "/repos/{owner}/{repo}/labels": map[string]any{
188 "get": map[string]any{"summary": "List labels", "security": []any{map[string]any{"bearer": []any{}}}, "responses": map[string]any{"200": map[string]any{"description": "Labels."}}},
189 "post": map[string]any{"summary": "Create or update a label", "description": "Maintainer only. Name uses letters, digits, spaces, hyphens or underscores. Color is # and six hex digits.", "security": []any{map[string]any{"bearer": []any{}}}, "responses": map[string]any{"201": map[string]any{"description": "Saved label."}, "403": map[string]any{"description": "Not a maintainer."}}},
190 },
191 "/repos/{owner}/{repo}/milestones": map[string]any{
192 "get": map[string]any{"summary": "List milestones", "security": []any{map[string]any{"bearer": []any{}}}, "responses": map[string]any{"200": map[string]any{"description": "Milestones."}}},
193 "post": map[string]any{"summary": "Create or update a milestone", "description": "Maintainer only. due_on is YYYY-MM-DD or empty.", "security": []any{map[string]any{"bearer": []any{}}}, "responses": map[string]any{"201": map[string]any{"description": "Saved milestone."}, "403": map[string]any{"description": "Not a maintainer."}}},
194 },
195 },
196 "webhooks": map[string]any{
197 "pipeline": post("Pipeline finished", "#/components/schemas/PipelineEvent"),
198 "push": post("Push", "#/components/schemas/PushEvent"),
199 "merge_request": post("Merge request", "#/components/schemas/MergeRequestEvent"),
200 "release": post("Release published", "#/components/schemas/ReleaseEvent"),
201 "issue": post("Issue", "#/components/schemas/IssueEvent"),
202 },
203 "components": map[string]any{
204 "securitySchemes": map[string]any{
205 "bearer": map[string]any{"type": "http", "scheme": "bearer", "description": "Personal access token (bg_)."},
206 },
207 "schemas": map[string]any{
208 "PipelineEvent": obj("pipeline_success or pipeline_failure.", map[string]any{
209 "object_kind": str("Always pipeline."),
210 "type": str("pipeline_success or pipeline_failure."),
211 "project": str("owner/name."),
212 "actor": str("User who started the pipeline."),
213 "summary": str("One-line summary."),
214 "url": str("Pipeline page."),
215 "pipeline_id": str("Same id as pipeline.id, as text."),
216 "pipeline": map[string]any{"$ref": "#/components/schemas/Pipeline"},
217 "jobs": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/Job"}},
218 }, []string{"object_kind", "type", "project", "pipeline", "jobs"}),
219 "Pipeline": obj("The pipeline this event is about.", map[string]any{
220 "id": map[string]any{"type": "integer", "description": "Pipeline id."},
221 "status": str("success or failed."),
222 "ref": str("Full ref, such as refs/heads/master."),
223 "sha": str("Commit SHA."),
224 "commit_message": str("Subject and body of the commit."),
225 "author": str("User who started the pipeline."),
226 "duration": num("Seconds from start to finish."),
227 "url": str("Pipeline page."),
228 }, []string{"id", "status", "ref", "sha", "commit_message", "author", "duration"}),
229 "Job": obj("One job. log is always the console tail. log_url is present only when log_truncated is true.", map[string]any{
230 "name": str("Job name."),
231 "stage": str("Stage name."),
232 "status": str("Job status."),
233 "duration": num("Seconds the job ran."),
234 "allow_failure": boolean("True when a failure does not fail the pipeline."),
235 "web_url": str("Job page."),
236 "log": str("Last 200 lines of the console output, at most 64 KiB. Secrets of at least 8 characters are [MASKED]."),
237 "log_truncated": boolean("True when log is shorter than the stored console output."),
238 "cancel_reason": str("Only for status canceled: superseded (a newer pipeline started for the same ref; shown as Obsolete) or manual."),
239 "failure_reason": str("Only for status failed, when known: job_execution_timeout, script_failure or runner_system_failure."),
240 "log_url": str("GET /api/v1/repos/{owner}/{repo}/jobs/{id}/log. Present only when log_truncated is true. Requires Authorization Bearer and a personal token that can read the repo. The response is the full log as text/plain, with secrets masked."),
241 }, []string{"name", "stage", "status", "duration", "allow_failure", "web_url", "log", "log_truncated"}),
242 "PushEvent": obj("A branch or tag update.", map[string]any{
243 "object_kind": str("Always push."),
244 "type": str("Always push."),
245 "project": str("owner/name."),
246 "actor": str("User who pushed."),
247 "ref": str("Full ref."),
248 "before": str("Previous SHA, or 40 zeros when the ref is new."),
249 "after": str("New SHA."),
250 "commits": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/Commit"}},
251 }, []string{"object_kind", "type", "project", "ref", "before", "after", "commits"}),
252 "Commit": obj("One commit. The diff text is not included.", map[string]any{
253 "sha": str("Commit SHA."),
254 "message": str("Subject and body."),
255 "author": str("Name and email."),
256 "timestamp": str("Author time in RFC3339."),
257 "url": str("Commit page."),
258 "files": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/FileChange"}},
259 "diff_url": str("GET /api/v1/repos/{owner}/{repo}/commits/{sha}/diff. Requires Authorization Bearer and a personal token that can read the repo. The response is the unified diff as text/plain."),
260 }, []string{"sha", "message", "author", "timestamp", "url", "files", "diff_url"}),
261 "FileChange": obj("One changed file, without the diff text.", map[string]any{
262 "path": str("Path after the change."),
263 "status": str("added, modified, removed or renamed."),
264 "previous_path": str("Path before a rename."),
265 "additions": map[string]any{"type": "integer", "description": "Added lines. Zero for a binary file."},
266 "deletions": map[string]any{"type": "integer", "description": "Deleted lines. Zero for a binary file."},
267 "binary": boolean("True when the file is binary."),
268 }, []string{"path", "status", "additions", "deletions"}),
269 "MergeRequestEvent": obj("Opened, merged or commented.", map[string]any{
270 "object_kind": str("Always merge_request."),
271 "type": str("Always merge_request."),
272 "project": str("owner/name."),
273 "actor": str("User who did this action."),
274 "merge_request": map[string]any{"$ref": "#/components/schemas/MergeRequest"},
275 "comment": str("Comment text. Present only when action is commented."),
276 "event_name": str("merge_request_comment for a comment, otherwise merge_request."),
277 "note": map[string]any{"$ref": "#/components/schemas/Note"},
278 }, []string{"object_kind", "type", "event_name", "project", "merge_request"}),
279 "Note": obj("A comment. Present only when action is commented.", map[string]any{
280 "body": str("Comment text."),
281 "noteable_type": str("Issue or MergeRequest."),
282 "noteable_id": map[string]any{"type": "integer", "description": "Number of the issue or merge request."},
283 "author": str("User who wrote the comment."),
284 "url": str("Page of the issue or merge request."),
285 }, []string{"body", "noteable_type", "noteable_id", "url"}),
286 "MergeRequest": obj("The merge request.", map[string]any{
287 "id": map[string]any{"type": "integer", "description": "Number in the project."},
288 "title": str("Title."),
289 "description": str("Description. May be empty."),
290 "source_branch": str("Source branch."),
291 "target_branch": str("Target branch."),
292 "status": str("open, merged or closed."),
293 "author": str("User who opened the merge request."),
294 "action": str("opened, merged or commented."),
295 "url": str("Merge request page."),
296 "reviewers": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/Reviewer"}},
297 "comments": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/Comment"}},
298 "commits": map[string]any{"type": "array", "description": "Up to 20 commits on the source branch that the target does not have, oldest first.", "items": map[string]any{"$ref": "#/components/schemas/Commit"}},
299 "diff_stats": map[string]any{"$ref": "#/components/schemas/DiffStats"},
300 "diff_url": str("GET /api/v1/repos/{owner}/{repo}/merge-requests/{id}/diff. Requires Authorization Bearer and a personal token that can read the repo. The response is the three-dot unified diff as text/plain."),
301 }, []string{"id", "title", "description", "source_branch", "target_branch", "status", "author", "action", "reviewers", "comments", "commits", "diff_stats", "diff_url"}),
302 "Reviewer": obj("The current review of one person.", map[string]any{
303 "username": str("Username."),
304 "status": str("approved, changes, rejected or dismissed."),
305 }, []string{"username", "status"}),
306 "Comment": obj("One comment on the merge request.", map[string]any{
307 "id": map[string]any{"type": "integer", "description": "Comment id."},
308 "author": str("Username."),
309 "body": str("Comment text."),
310 "created_at": str("Time in RFC3339."),
311 "file_path": str("File, when the comment is on a line."),
312 "line_start": map[string]any{"type": "integer", "description": "First line."},
313 "line_end": map[string]any{"type": "integer", "description": "Last line."},
314 "parent_id": map[string]any{"type": "integer", "description": "Parent comment, when this is a reply."},
315 }, []string{"id", "author", "body", "created_at"}),
316 "DiffStats": obj("Line counts of the merge request diff. The diff text is not included.", map[string]any{
317 "additions": map[string]any{"type": "integer", "description": "Added lines."},
318 "deletions": map[string]any{"type": "integer", "description": "Deleted lines."},
319 "files": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/FileChange"}},
320 }, []string{"additions", "deletions", "files"}),
321 "ReleaseEvent": obj("A published release.", map[string]any{
322 "object_kind": str("Always release."),
323 "type": str("Always release_published."),
324 "project": str("owner/name."),
325 "release_tag": str("Same value as release.tag."),
326 "release": map[string]any{"$ref": "#/components/schemas/Release"},
327 }, []string{"object_kind", "type", "project", "release"}),
328 "Release": obj("The release.", map[string]any{
329 "tag": str("Tag name."),
330 "name": str("Release title."),
331 "commit": str("Commit SHA."),
332 "assets": map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/Asset"}},
333 }, []string{"tag", "name", "commit", "assets"}),
334 "Asset": obj("A file attached to the release.", map[string]any{
335 "name": str("File name."),
336 "url": str("Download URL."),
337 "size": map[string]any{"type": "integer", "description": "Size in bytes."},
338 }, []string{"name", "url", "size"}),
339 "IssueEvent": obj("Opened, updated, closed, reopened or commented.", map[string]any{
340 "object_kind": str("Always issue."),
341 "type": str("Always issue."),
342 "project": str("owner/name."),
343 "actor": str("User who did this action."),
344 "summary": str("One-line summary."),
345 "url": str("Issue page."),
346 "issue": map[string]any{"$ref": "#/components/schemas/Issue"},
347 "comment": str("Comment text. Present only when action is commented."),
348 "event_name": str("issue_opened, issue_closed, issue_reopened, issue_updated or issue_comment."),
349 "note": map[string]any{"$ref": "#/components/schemas/Note"},
350 }, []string{"object_kind", "type", "event_name", "project", "issue"}),
351 "Issue": obj("The issue this event is about.", map[string]any{
352 "id": map[string]any{"type": "integer", "description": "Number in the project."},
353 "title": str("Title."),
354 "description": str("Description. May be empty."),
355 "status": str("open or closed."),
356 "confidential": boolean("True when the issue is confidential."),
357 "author": str("User who opened the issue."),
358 "assignees": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
359 "labels": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
360 "milestone": str("Milestone title, or empty."),
361 "due_date": str("Due date as YYYY-MM-DD, or empty."),
362 "action": str("opened, updated, closed, reopened or commented."),
363 "url": str("Issue page."),
364 }, []string{"id", "title", "description", "status", "confidential", "author", "assignees", "labels", "milestone", "due_date", "action"}),
365 },
366 },
367 }
368 raw, err := json.MarshalIndent(doc, "", " ")
369 if err != nil {
370 return []byte("{}\n")
371 }
372 return append(raw, '\n')
373}