Merge remote-tracking branch 'origin/main' into add-platform-area-to-…

…buildkite-docs

pages/apis/rest_api/package_registries/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):
+
+<table class="responsive-table">
+  <tbody>
+    <tr><th><code>name</code></th><td>Filters the results by the package name.<br><em>Example:</em> <code>?name=banana</code>.</td></tr>
+  </tbody>
+</table>
+
+Required scope: `read_packages`
+
+Success response: `200 OK`
+
 ## Get a package
 
 Returns the details for a single package.
@@ -103,14 +151,28 @@ Success response: `200 OK`
 
 ## Copy a package
 
-Copies a package from a source registry to a destination registry.
+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" \
   -X POST "https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{source_registry.slug}/packages/{package.id}/copy?to={destination_registry.slug}"
   -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).
+
+The following type of response is returned by Buildkite upon a successful `curl` copying event.
+
 ```json
 {
   "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",

pages/apis/rest_api/package_registries/registries.md

@@ -57,6 +57,8 @@ Optional [request body properties](/docs/api#request-body-properties):
 <table class="responsive-table">
   <tbody>
     <tr><th><code>description</code></th><td>Description of the registry.<br><em>Default value:</em> <code>null</code>.</td></tr>
+    <tr><th><code>emoji</code></th><td>Emoji for the registry using the <a href="/docs/apis/rest-api/emojis">emoji syntax</a>.<br><em>Example:</em> <code>"\:sunflower\:"</code>.</td></tr>
+    <tr><th><code>color</code></th><td>Color hex code for the registry.<br><em>Example:</em> <code>"#f0ccff"</code>.</td></tr>
     <tr><th><code>oidc_policy</code></th><td>A policy matching a <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-basic-oidc-policy-format">basic</a> or <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-complex-oidc-policy-example">more complex</a> OIDC policy format. Can be either stringified YAML, or a JSON array of policy statements.<br><em>Default value:</em> <code>null</code>.</td></tr>
   </tbody>
 </table>

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](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:

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