Merge remote-tracking branch 'origin/main' into service-quotas

buildkite · Oct 20, 2024 · a77fccb · a77fccb
2 parents 6578eb6 + 7409338
commit a77fccb
Show file tree

Hide file tree

Showing 276 changed files with 7,524 additions and 3,654 deletions.
diff --git a/.buildkite/pipeline.deploy.yml b/.buildkite/pipeline.deploy.yml
@@ -1,3 +1,6 @@
+env:
+  BUILDKIT_PROGRESS: plain
+
 steps:
   - name: ":docker::ecr: Push to ECR"
     command: ".buildkite/push-image.sh"
@@ -9,7 +12,7 @@ steps:
       queue: elastic-runners
     plugins:
       - aws-assume-role-with-web-identity#v1.0.0:
-          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-main
+          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-private
       - ecr#v2.7.0:
           login: true
           account-ids: ${ECR_ACCOUNT_ID}
@@ -21,7 +24,7 @@ steps:
     depends_on: "ecr-push"
     plugins:
       - aws-assume-role-with-web-identity#v1.0.0:
-          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-main
+          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-private
       - buildkite/ecr-scan-results#v2.0.0:
           image-name: "${ECR_REPO}:${BUILDKITE_BUILD_NUMBER}"
           fail-build-on-plugin-failure: true
@@ -52,7 +55,7 @@ steps:
     command: scripts/deploy-ecs
     plugins:
       - aws-assume-role-with-web-identity#v1.0.0:
-          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-main
+          role-arn: arn:aws:iam::${ECR_ACCOUNT_ID}:role/pipeline-buildkite-docs-private
 
   - wait
 

diff --git a/.buildkite/pipeline.graphql.yml b/.buildkite/pipeline.graphql.yml
@@ -1,3 +1,10 @@
 steps:
   - label: Update GraphQL docs
     command: .buildkite/update_graphql_docs
+    plugins:
+      - aws-assume-role-with-web-identity#v1.0.0:
+          role-arn: arn:aws:iam::445615400570:role/pipeline-buildkite-docs-private
+      - aws-ssm#v1.0.0:
+          parameters:
+            GH_TOKEN: /pipelines/buildkite/docs-private/gh-token
+            API_ACCESS_TOKEN: /pipelines/buildkite/docs-private/api-access-token
diff --git a/.buildkite/pipeline.preview.yml b/.buildkite/pipeline.preview.yml
@@ -1,18 +1,42 @@
+env:
+  BUILDKIT_PROGRESS: plain
+
 steps:
   - label: "Prepare preview"
     command: bin/prepare-preview
+    key: prepare-preview
+    plugins:
+      - aws-assume-role-with-web-identity#v1.0.0:
+          role-arn: arn:aws:iam::445615400570:role/pipeline-buildkite-docs-private
+      - aws-ssm#v1.0.0:
+          parameters:
+            GH_TOKEN: /pipelines/buildkite/docs-private/gh-token
+            BUILDKITE_ANALYTICS_TOKEN: /pipelines/buildkite/docs-private/buildkite-analytics-token
+            NETLIFY_AUTH_TOKEN: /pipelines/buildkite/docs-private/netlify-auth-token
+            NETLIFY_SITE_ID: /pipelines/buildkite/docs-private/netlify-site-id
 
   - label: "Deploy preview"
     command: bin/deploy-preview
+    depends_on: prepare-preview
     env:
       RAILS_ENV: "production"
     plugins:
+      - aws-assume-role-with-web-identity#v1.0.0:
+          role-arn: arn:aws:iam::445615400570:role/pipeline-buildkite-docs-private
+      - aws-ssm#v1.0.0:
+          parameters:
+            GH_TOKEN: /pipelines/buildkite/docs-private/gh-token
+            BUILDKITE_ANALYTICS_TOKEN: /pipelines/buildkite/docs-private/buildkite-analytics-token
+            NETLIFY_AUTH_TOKEN: /pipelines/buildkite/docs-private/netlify-auth-token
+            NETLIFY_SITE_ID: /pipelines/buildkite/docs-private/netlify-site-id
       - docker-compose#v3.9.0:
           run: app
           dependencies: false
           mount-buildkite-agent: true
           env:
+            - GH_REPO
             - GH_TOKEN
             - NETLIFY_AUTH_TOKEN
             - NETLIFY_SITE_ID
+            - NETLIFY_SALT
             - BUILDKITE_BRANCH
diff --git a/.buildkite/pipeline.sync.yml b/.buildkite/pipeline.sync.yml
@@ -0,0 +1,13 @@
+#docs-private-to-public-sync
+notify:
+  - slack: "$SLACK_CHANNEL"
+    if: build.state != "passed"
+env:
+  PUBLIC_REPO: [email protected]:buildkite/docs.git
+steps:
+  - label: Sync to public mirror
+    branches: main
+    commands: |
+      echo "+++ :git: Syncing to public mirror"
+
+      git push "${PUBLIC_REPO}" ${BUILDKITE_COMMIT}:main
diff --git a/.buildkite/pipeline.sync_public_pr.yml b/.buildkite/pipeline.sync_public_pr.yml
@@ -0,0 +1,27 @@
+steps:
+  # NOTE: this input step is in the pipeline steps on Buildkite
+  # - block: "Which PR needs to be synced?"
+  #   fields:
+  #     - key: pull_request_number
+  #       required: true
+  #       text: "Pull Request Number"
+  #       format: "^[0-9]+$"
+  #       hint: "Find the PR number on https://github.com/buildkite/docs/pulls"
+
+  - label: ":git: Sync Public PR to Private Repo"
+    command: "bin/sync-public-pr"
+    plugins:
+      - aws-assume-role-with-web-identity#v1.0.0:
+          role-arn: arn:aws:iam::445615400570:role/pipeline-buildkite-docs-private
+      - aws-ssm#v1.0.0:
+          parameters:
+            GH_TOKEN: /pipelines/buildkite/docs-private/gh-token
+      - docker#v5.11.0:
+          image: "ruby:3.3-bookworm"
+          propagate-environment: true
+          mount-buildkite-agent: true
+          mount-ssh-agent: true
+          environment:
+            - GH_TOKEN
+            - GH_PRIVATE_REPO
+            - GH_PUBLIC_REPO
diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml
@@ -1,3 +1,6 @@
+env:
+  BUILDKIT_PROGRESS: plain
+
 steps:
   - label: ":spider: muffet"
     # We need to wait until rails has started before running muffet as otherwise it will error out
@@ -56,7 +59,7 @@ steps:
               login: true
               account-ids: public.ecr.aws
           - docker#v3.7.0:
-              image: "public.ecr.aws/docker/library/node:lts-alpine3.14"
+              image: "public.ecr.aws/docker/library/node:lts-alpine3.16"
 
       - label: ":lint-roller: Linting text and markdown"
         agents:
@@ -80,9 +83,7 @@ steps:
           # version, is way faster because we don't have to wait for Ruby gems to
           # install.
           - docker#v3.7.0:
-              # Alpine 3.14 - EOS 01 May 2023
-              # lts = Node 1415.1 - 2023-04-30
-              image: "public.ecr.aws/docker/library/node:lts-alpine3.14"
+              image: "public.ecr.aws/docker/library/node:lts-alpine3.16"
 
       - label: "Validate YAML"
         command:
@@ -97,7 +98,7 @@ steps:
               login: true
               account-ids: public.ecr.aws
           - docker#v3.7.0:
-              image: "public.ecr.aws/docker/library/node:lts-alpine3.14"
+              image: "public.ecr.aws/docker/library/node:lts-alpine3.16"
 
       - label: ":lint-roller: :markdown: Linting the Markdown"
         command: npm run -y mdlint
@@ -110,7 +111,7 @@ steps:
               login: true
               account-ids: public.ecr.aws
           - docker#v3.7.0:
-              image: "public.ecr.aws/docker/library/node:lts-alpine3.14"
+              image: "public.ecr.aws/docker/library/node:lts-alpine3.16"
 
       - label: ":snake: Linting markdown files for snake case"
         command: npx -y @ls-lint/[email protected]
@@ -123,7 +124,7 @@ steps:
               login: true
               account-ids: public.ecr.aws
           - docker#v3.7.0:
-              image: "public.ecr.aws/docker/library/node:lts-alpine3.14"
+              image: "public.ecr.aws/docker/library/node:lts-alpine3.16"
 
   - label: ":rspec: RSpec"
     depends_on: linting

diff --git a/.buildkite/update_graphql_docs b/.buildkite/update_graphql_docs
@@ -38,8 +38,10 @@ git config user.email $GIT_EMAIL
 git config user.name $GIT_NAME
 git checkout -b $BRANCH
 git commit -m "Update GraphQL docs"
-git push -u origin $BRANCH
+
+TARGET_REPO="https://dummy-user:${GH_TOKEN}@github.com/${GH_REPO}"
+git push -f "${TARGET_REPO}" HEAD:${BRANCH}
 
 echo "+++ Create pull request"
-create_pull_request "Update GraphQL docs" "This is an automated PR based on the current GraphQL schema" \
+create_pull_request "Update GraphQL docs" "This is an automated PR based on the current GraphQL schema" "${BRANCH}" \
   | jq ".html_url" | buildkite-agent annotate --style "success"
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1 @@
+* @buildkite/docs
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -2,8 +2,8 @@ agent:
   - pages/agent/**/*
 cli:
   - pages/cli/**/*
-test-analytics:
-  - pages/test_analytics/**/*
+test-engine:
+  - pages/test_engine/**/*
 pipelines:
   - pages/pipelines/**/*
   - pages/tutorials/**/*

diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-16.19.1
+18.16.0
diff --git a/.ruby-version b/.ruby-version
@@ -1 +1 @@
-3.3.3
+3.3.5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,32 +11,34 @@ Please also note the following style guides, which are relevant to adding conten
 
 The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup.
 
+As a public contributor to the Buildkite Docs, you should work with a fork of [this upstream repository](https://github.com/buildkite/docs) in your own GitHub account, and then create pull requests to this upstream.
+
 ### Add a new docs page and nav entry
 
 To add a new documentation (docs) page and a nav entry for it:
 
 1. Create the file as a new Markdown file (with the extension `.md`) within the appropriate `pages` directory. Ensure the file name is written in all lowercase letters, and separate words using underscores. (These underscores will be automatically converted to hyphens when the Buildkite Docs site is rebuilt.)
 
-1. Add a corresponding entry to this new page in the [`data/nav.yml`](./data/nav.yml) file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`:
+1. Add a corresponding entry to this new page in the [`./data/nav.yml`](./data/nav.yml) file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`:
 
-| Key           | Description | Data type |
-| ------------- | ----------- | --------- |
-| `name`        | Nav entry name (see note below). | String, required |
-| `path`        | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links, although this practice should be avoided or minimized. If the `path` is empty or omitted, then this will be rendered as a toggle that opens a new section of pages. | String, optional |
-| `icon`        | Prepend with an icon. | String, optional |
-| `theme`       | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple`. | String, optional |
-| `children`    | Child nav entry items. | Array of objects, optional |
-| `pill`        | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional |
-| `new_window`  | Make this link open up a new window, although this practice should be avoided or minimized. | Bool, optional |
-| `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional |
+    | Key           | Description | Data type |
+    | ------------- | ----------- | --------- |
+    | `name`        | Nav entry name (see note below). | String, required |
+    | `path`        | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links, although this practice should be avoided or minimized. If the `path` is empty or omitted, then this will be rendered as a toggle that opens a new section of pages. | String, optional |
+    | `icon`        | Prepend with an icon. | String, optional |
+    | `theme`       | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple`. | String, optional |
+    | `children`    | Child nav entry items. | Array of objects, optional |
+    | `pill`        | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional |
+    | `new_window`  | Make this link open up a new window, although this practice should be avoided or minimized. | Bool, optional |
+    | `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional |
 
 > [!NOTE]
 > Whenever you save changes to the `nav.yml` file, you'll need to stop and restart your local development environment in order to see these changes reflected in the nav.
-> 
+>
 > The Buildkite Docs web site is kept running with Ruby, which interprets underscores in filenames as hyphens. Therefore, if a page is called `octopussy_cat.md`, then for its entry in the `nav.yml` file, you need to reference its `path` key value as `octopussy-cat`.
-> 
+>
 > If you're creating a new section for the nav, then as described for the `path` key above, add the `name` key for this entry, omit its `path` key, and add a `children` key to create this new section. Then, nest/indent all new page entries within this section entry.
-> 
+>
 > Since a new section entry in the nav is purely a toggle that cannot hold page content itself, then to introduce a page for this new section, create a top-level "Overview" page for this section instead.
 
 ### Linting
@@ -64,9 +66,9 @@ The rules enabled for this Markdown linting are defined in the [`.markdownlint.y
 
 The Buildkite Docs build pipeline uses [Vale](https://vale.sh/) to check for spelling errors, and builds will fail if a spelling error is encountered.
 
-If you need to add an exception to this (for example, you are referencing a new technology or tool that isn't in Vale's vocabulary), add this term verbatim to the [`/vale/styles/vocab.txt`](./vale/styles/vocab.txt) file, ensuring that the term is added in the correct alphabetical order within the file. Case is important but should be ignored with regard to alphabetical ordering within the file. This makes it easier to identify if an exception has already been added.
+If you need to add an exception to this (for example, you are referencing a new technology or tool that isn't in Vale's vocabulary), add this term verbatim to the [`./vale/styles/vocab.txt`](./vale/styles/vocab.txt) file, ensuring that the term is added in the correct alphabetical order within the file. Case is important but should be ignored with regard to alphabetical ordering within the file. This makes it easier to identify if an exception has already been added.
 
-If you encounter a spelling error within a heading, add this entry into the [`/vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file.
+If you encounter a spelling error within a heading, add this entry into the [`./vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file.
 
 #### Escape vale linting
 
@@ -114,13 +116,14 @@ To save yourself a few unnecessary rounds of edits in the future, remember that
 
 #### Beta flags
 
-To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the `app/models/beta_pages.rb` file.
+To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the [`./app/models/beta_pages.rb`](./app/models/beta_pages.rb) file.
 
 For example:
 ```
 [
-  'test-analytics',
-  'test-analytics/integrations'
+  'pipelines/some-new-beta-feature',
+  'test-engine/some-new-beta-feature',
+  'package-registries/some-new-beta-feature'
 ]
 ```
 
@@ -130,7 +133,7 @@ Adding the class `has-pill-beta` to any element will append the beta pill. This
 
 #### Table of contents
 
-Table of contents are automatically generated based on `##`-level headings.
+An in-page table of contents (with the **On this page** title) is automatically generated based on `##`-level headings.
 
 You can omit a table of contents by adding some additional metadata to a Markdown template using the following YAML front matter:
 
@@ -243,10 +246,10 @@ This information was aggregated by going over the existing screenshots in the do
 > Before you proceed, make sure that both the width and the height of the image are an even number of pixels!
 
 Steps for adding add an image to a documentation page:
-1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page)
-2. Put the file into the corresponding `images` folder (a folder with the same name as the page you are adding this image to; create such folder if it doesn't exist yet)
-3. Compose relevant alt text for the image file using sentence case
-4. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`.
+1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page).
+1. Save the file into its corresponding `images` folder (that is, a sub-folder within `images` whose path and name respectively matches that of the Markdown page's path within `pages` and the name this image file is referenced by on this page). Create this sub-folder hierarchy if it doesn't yet exist within `images`.
+1. Compose relevant alt text for the image file using sentence case.
+1. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`.
 For large images/screenshots taken on a retina screen, use `<%= image "your-image.png", width: 1110/2, height: 1110/2, alt: "Screenshot of Important Feature" %>`.
 
 ## Talking about YAML

diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,4 @@
-ARG BASE_IMAGE=public.ecr.aws/docker/library/ruby:3.3.3-slim-bookworm@sha256:bc6372a998e79b5154c8132d1b3e0287dc656249f71f48487a1ecf0d46c9c080
+ARG BASE_IMAGE=public.ecr.aws/docker/library/ruby:3.3.5-slim-bookworm
 ARG NODE_IMAGE=public.ecr.aws/docker/library/node:18-bookworm-slim@sha256:d2d8a6420c9fc6b7b403732d3a3c5395d016ebc4996f057aad1aded74202a476
 
 FROM $BASE_IMAGE AS builder