From 0d48805c01d6a3779c0818170ace497ba6fd8d53 Mon Sep 17 00:00:00 2001 From: Tim Riley Date: Thu, 8 Feb 2024 16:12:45 +1100 Subject: [PATCH] Add REST API docs for creating annotations (#2546) Add REST API docs for creating annotations While here, add missing attributes to jobs in builds: - parallel_group_index - parallel_group_total - matrix - cluster_id - cluster_url - cluster_queue_id - cluster_queue_url Just null for these for now (they're all optional), but we should look to expand on these in the future. --- pages/apis/rest_api/annotations.md | 74 ++++++++++++++++++++++++++++++ pages/apis/rest_api/builds.md | 49 +++++++++++++++++--- pages/apis/rest_api/pipelines.md | 2 +- 3 files changed, 117 insertions(+), 8 deletions(-) diff --git a/pages/apis/rest_api/annotations.md b/pages/apis/rest_api/annotations.md index 4b694e2652..cbb74ba3d0 100644 --- a/pages/apis/rest_api/annotations.md +++ b/pages/apis/rest_api/annotations.md @@ -51,3 +51,77 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline. Required scope: `read_builds` Success response: `200 OK` + +## Create an annotation on a build + +Creates an annotation on a build. + +>📘 +> Note that you need the build number to create annotations, not the build ID. + +```bash +curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/annotations" \ + -H "Content-Type: application/json" \ + -d '{ + "body": "Hello world!", + "style": "info", + "context": "greeting" + }' +``` + +```json +{ + "id": "018b8d10-6b5b-4df2-b0ff-dfa2af566050", + "context": "greeting", + "style": "info", + "body_html": "

Hello world!

\n", + "created_at": "2023-11-01T22:45:45.435Z", + "updated_at": "2023-11-01T22:45:45.435Z" +} +``` + +Required [request body properties](/docs/api#request-body-properties): + + + + + + + + +
body + The annotation's body, as HTML or Markdown. +

Example: "My annotation here"

+
+ +Optional [request body properties](/docs/api#request-body-properties): + + + + + + + + + + + + + + + + +
style + The style of the annotation. Can be success, info, warning or error. +

Example: "info"

+
context + A string value by which to identify the annotation on the build. This is useful when appending to an existing annotation. Only one annotation per build may have any given context value. +

Example: "coverage"

+
append + Whether to append the given body onto the annotation with the same context. +

Example: true

+
+ +Required scope: `write_builds` + +Success response: `201 Created` diff --git a/pages/apis/rest_api/builds.md b/pages/apis/rest_api/builds.md index 925b02e008..0002147994 100644 --- a/pages/apis/rest_api/builds.md +++ b/pages/apis/rest_api/builds.md @@ -124,9 +124,16 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline. "started_at": "2015-05-09T21:07:59.874Z", "finished_at": "2015-05-09T21:08:59.874Z", "retried": false, - "retried_in_job_id": null, - "retries_count": null, - "retry_type": null + "retried_in_job_id": null, + "retries_count": null, + "retry_type": null, + "parallel_group_index": null, + "parallel_group_total": null, + "matrix": null, + "cluster_id": null, + "cluster_url": null, + "cluster_queue_id": null, + "cluster_queue_url": null } ], "created_at": "2015-05-09T21:05:59.874Z", @@ -276,7 +283,14 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline. "retried": false, "retried_in_job_id": null, "retries_count": null, - "retry_type": null + "retry_type": null, + "parallel_group_index": null, + "parallel_group_total": null, + "matrix": null, + "cluster_id": null, + "cluster_url": null, + "cluster_queue_id": null, + "cluster_queue_url": null } ], "created_at": "2015-05-09T21:05:59.874Z", @@ -439,7 +453,14 @@ curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{p "retried": false, "retried_in_job_id": null, "retries_count": null, - "retry_type": null + "retry_type": null, + "parallel_group_index": null, + "parallel_group_total": null, + "matrix": null, + "cluster_id": null, + "cluster_url": null, + "cluster_queue_id": null, + "cluster_queue_url": null } ], "created_at": "2015-05-09T21:05:59.874Z", @@ -605,7 +626,14 @@ curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pi "retried": false, "retried_in_job_id": null, "retries_count": null, - "retry_type": null + "retry_type": null, + "parallel_group_index": null, + "parallel_group_total": null, + "matrix": null, + "cluster_id": null, + "cluster_url": null, + "cluster_queue_id": null, + "cluster_queue_url": null } ], "created_at": "2015-05-09T21:05:59.874Z", @@ -745,7 +773,14 @@ curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pi "retried": false, "retried_in_job_id": null, "retries_count": null, - "retry_type": null + "retry_type": null, + "parallel_group_index": null, + "parallel_group_total": null, + "matrix": null, + "cluster_id": null, + "cluster_url": null, + "cluster_queue_id": null, + "cluster_queue_url": null } ], "created_at": "2015-05-09T21:05:59.874Z", diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index 2efa6f5d63..3f0f1a282d 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/pages/apis/rest_api/pipelines.md @@ -1035,7 +1035,7 @@ curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{s Required scope: `write_pipelines` -Success response: `201 CREATED` +Success response: `201 Created` Error responses: