From 014d66f21e655d1abcada838d76d0cfd23088f71 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Fri, 4 Oct 2024 17:16:37 +0900 Subject: [PATCH 01/10] Added emoji and color to optional request body properties table --- pages/apis/rest_api/packages/registries.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 10d4978044..555d7843ef 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -57,6 +57,8 @@ Optional [request body properties](/docs/api#request-body-properties): + +
descriptionDescription of the registry.
Default value: null.
emojiEmoji for the registry using the emoji syntax.
Example: "\:sunflower\:".
colorColor hex code for the registry.
Example: "#f0ccff".
oidc_policyA policy matching a basic or more complex OIDC policy format. Can be either stringified YAML, or a JSON array of policy statements.
Default value: null.
From 9e5418ff8704cbe93209096db7954ae227d8f9de Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Mon, 7 Oct 2024 18:07:13 +0900 Subject: [PATCH 02/10] api docs for packages#index --- pages/apis/rest_api/packages/packages.md | 48 ++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md index 95d0666c2b..f319f625a2 100644 --- a/pages/apis/rest_api/packages/packages.md +++ b/pages/apis/rest_api/packages/packages.md @@ -66,6 +66,54 @@ Required scope: `write_packages` Success response: `200 OK` +## List all packages + +Returns a [paginated list](<%= paginated_resource_docs_url %>) of all packages in a registry. +Packages are listed in the order they were created (newest first). + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X GET "https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages" +``` + +```json +{ + "items": [ + { + "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44", + "url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44", + "web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44", + "name": "banana", + "created_at": "2024-08-22T06:24:53Z", + "version": "1.0" + }, + { + "id": "019178c2-6b08-7d66-a1db-b79b8ba83151", + "url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/packages/019178c2-6b08-7d66-a1db-b79b8ba83151", + "web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry/packages/019178c2-6b08-7d66-a1db-b79b8ba83151", + "name": "grapes", + "created_at": "2024-08-21T06:24:53Z", + "version": "2.8.3" + } + ], + "links": { + "self": "https://api.buildkite.localhost/v2/packages/organizations/my_great_org/registries/my-registry/packages", + } +} +``` + +Optional [query string parameters](/docs/api#query-string-parameters): + + + + + +
nameFilters the results by the package name.
Example: ?name=banana.
+ +Required scope: `read_packages` + +Success response: `200 OK` + ## Get a package Returns the details for a single package. From 1ae2e9613f1d7c4dc5c518ad025cfdb3b47d03a6 Mon Sep 17 00:00:00 2001 From: Steven Webb Date: Tue, 8 Oct 2024 10:10:32 +0800 Subject: [PATCH 03/10] Document packages#copy api supported package types --- pages/apis/rest_api/packages/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md index 95d0666c2b..785714812a 100644 --- a/pages/apis/rest_api/packages/packages.md +++ b/pages/apis/rest_api/packages/packages.md @@ -103,7 +103,7 @@ Success response: `200 OK` ## Copy a package -Copies a package from a source registry to a destination registry. +Copies a package from a source registry to a destination registry. Note, this API is not available for all package types. Currently it supports Alpine, Deb, Gem, NodeJS, Python, RPM, and generic files. If you wish to copy an unsupported package type please contact support. ```bash curl -H "Authorization: Bearer $TOKEN" \ From dbb97d4b65ae03ed016ad53577f48cf63c5c0656 Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 8 Oct 2024 13:31:49 +1000 Subject: [PATCH 04/10] Update Prepare your Amazon S3 bucket section for Build Exports doc to include safety mechanisms for large data dumps --- pages/pipelines/build_exports.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pages/pipelines/build_exports.md b/pages/pipelines/build_exports.md index 1a6f255a4e..67b477e043 100644 --- a/pages/pipelines/build_exports.md +++ b/pages/pipelines/build_exports.md @@ -51,6 +51,9 @@ To configure build exports for your organization, you'll need to prepare an Amaz - [Server-side data encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html) (`SSE-S3` is enabled by default, we do not currently support `SSE-KMS` but let us know if you need it). - [S3 Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) to help recover objects from accidental deletion or overwrite. * You may want to use [Amazon S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to manage storage class and object expiry. +* You may want to set up additional safety mechanisms for large data dumps: +- We recommend setting up logging and alerts (e.g., using AWS CloudWatch) to monitor usage and set thresholds for data upload limits. +- Use cost monitoring with AWS Budgets or CloudWatch to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. ¹ Your S3 bucket policy should look like this, with `YOUR-BUCKET-NAME-HERE` and `YOUR-BUILDKITE-ORGANIZATION-UUID` substituted with your details: From d77d0c16b69b46fe7fdbcc94fed3d8bde7f2582b Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 8 Oct 2024 13:42:01 +1000 Subject: [PATCH 05/10] adding hyperlinks --- pages/pipelines/build_exports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/pipelines/build_exports.md b/pages/pipelines/build_exports.md index 67b477e043..52f3884d38 100644 --- a/pages/pipelines/build_exports.md +++ b/pages/pipelines/build_exports.md @@ -52,8 +52,8 @@ To configure build exports for your organization, you'll need to prepare an Amaz - [S3 Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) to help recover objects from accidental deletion or overwrite. * You may want to use [Amazon S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to manage storage class and object expiry. * You may want to set up additional safety mechanisms for large data dumps: -- We recommend setting up logging and alerts (e.g., using AWS CloudWatch) to monitor usage and set thresholds for data upload limits. -- Use cost monitoring with AWS Budgets or CloudWatch to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. +- We recommend setting up logging and alerts (e.g., using [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)) to monitor usage and set thresholds for data upload limits. +- Use cost monitoring with [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) or [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. ¹ Your S3 bucket policy should look like this, with `YOUR-BUCKET-NAME-HERE` and `YOUR-BUILDKITE-ORGANIZATION-UUID` substituted with your details: From c2a6e2f53ee7166ecbd78e5c08fbd7ec1c2ecaa1 Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 8 Oct 2024 13:48:27 +1000 Subject: [PATCH 06/10] linting fix --- pages/pipelines/build_exports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/pipelines/build_exports.md b/pages/pipelines/build_exports.md index 52f3884d38..60e1b2cddd 100644 --- a/pages/pipelines/build_exports.md +++ b/pages/pipelines/build_exports.md @@ -52,8 +52,8 @@ To configure build exports for your organization, you'll need to prepare an Amaz - [S3 Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) to help recover objects from accidental deletion or overwrite. * You may want to use [Amazon S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to manage storage class and object expiry. * You may want to set up additional safety mechanisms for large data dumps: -- We recommend setting up logging and alerts (e.g., using [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)) to monitor usage and set thresholds for data upload limits. -- Use cost monitoring with [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) or [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. + - We recommend setting up logging and alerts (e.g., using [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)) to monitor usage and set thresholds for data upload limits. + - Use cost monitoring with [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) or [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. ¹ Your S3 bucket policy should look like this, with `YOUR-BUCKET-NAME-HERE` and `YOUR-BUILDKITE-ORGANIZATION-UUID` substituted with your details: From c955038bc4e53ea163f89614a08a8753a3fd7738 Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 8 Oct 2024 14:06:45 +1000 Subject: [PATCH 07/10] removing comma --- pages/pipelines/build_exports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/build_exports.md b/pages/pipelines/build_exports.md index 60e1b2cddd..04c26f02e3 100644 --- a/pages/pipelines/build_exports.md +++ b/pages/pipelines/build_exports.md @@ -52,7 +52,7 @@ To configure build exports for your organization, you'll need to prepare an Amaz - [S3 Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) to help recover objects from accidental deletion or overwrite. * You may want to use [Amazon S3 Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to manage storage class and object expiry. * You may want to set up additional safety mechanisms for large data dumps: - - We recommend setting up logging and alerts (e.g., using [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)) to monitor usage and set thresholds for data upload limits. + - We recommend setting up logging and alerts (e.g. using [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)) to monitor usage and set thresholds for data upload limits. - Use cost monitoring with [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) or [AWS CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) to track large or unexpected uploads that may lead to high costs. Setting budget alerts can help you detect unexpected increases in usage early. ¹ Your S3 bucket policy should look like this, with `YOUR-BUCKET-NAME-HERE` and From 41ca311840b18c6dedc46eb2b4db5335b3881e31 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 8 Oct 2024 17:14:29 +1100 Subject: [PATCH 08/10] Copy a package REST API reference instructions - modify supported package ecosystems sentences to match those earlier on the page for publishing a package. --- pages/apis/rest_api/packages/packages.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md index 785714812a..169f0c62d9 100644 --- a/pages/apis/rest_api/packages/packages.md +++ b/pages/apis/rest_api/packages/packages.md @@ -103,7 +103,7 @@ Success response: `200 OK` ## Copy a package -Copies a package from a source registry to a destination registry. Note, this API is not available for all package types. Currently it supports Alpine, Deb, Gem, NodeJS, Python, RPM, and generic files. If you wish to copy an unsupported package type please contact support. +For some supported [package ecosystems](/docs/packages/ecosystems), copies a package from a source registry to a destination registry. ```bash curl -H "Authorization: Bearer $TOKEN" \ @@ -111,6 +111,18 @@ curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" ``` +Currently, this REST API call only supports package types belonging to the following package ecosystems: + +- [Alpine (apk)](/docs/packages/alpine) +- [Debian/Ubuntu (deb)](/docs/packages/debian) +- [Files (generic)](/docs/packages/files) +- [JavaScript (npm)](/docs/packages/javascript) +- [Python (PyPI)](/docs/packages/python) +- [Red Hat (RPM)](/docs/packages/red-hat) +- [Ruby (RubyGems)](/docs/packages/ruby) + +If you wish this feature to be available for package types belonging to other package ecosystems, please contact [support](https://buildkite.com/support). + ```json { "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44", From 7b18840a853d0e1f60a7078ac7e86438c9f4b953 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 8 Oct 2024 17:24:44 +1100 Subject: [PATCH 09/10] Add line to introduce response for curl copy. --- pages/apis/rest_api/packages/packages.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md index 169f0c62d9..6161a71ef0 100644 --- a/pages/apis/rest_api/packages/packages.md +++ b/pages/apis/rest_api/packages/packages.md @@ -123,6 +123,8 @@ Currently, this REST API call only supports package types belonging to the follo If you wish this feature to be available for package types belonging to other package ecosystems, please contact [support](https://buildkite.com/support). +The following type of response is returned by Buildkite upon a successful `curl` copying event. + ```json { "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44", From 5675a02c456a0c159272758474b1f3614435a0d0 Mon Sep 17 00:00:00 2001 From: Ken Thompson Date: Wed, 9 Oct 2024 06:30:33 +1100 Subject: [PATCH 10/10] Update mac.md Add gcloud CLI to hosted agents --- pages/pipelines/hosted_agents/mac.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pages/pipelines/hosted_agents/mac.md b/pages/pipelines/hosted_agents/mac.md index c737443804..f6dd6c9577 100644 --- a/pages/pipelines/hosted_agents/mac.md +++ b/pages/pipelines/hosted_agents/mac.md @@ -125,6 +125,7 @@ Updated Xcode versions will be available one week after Apple offers them for do - AWS CLI - Azure CLI +- gcloud CLI - CodeQL - Bicep CLI - fastlane