From 367a07f81093f3169ef5fbcd811801265a609620 Mon Sep 17 00:00:00 2001 From: Andrew DiMola Date: Wed, 3 Sep 2025 14:50:36 -0400 Subject: [PATCH 1/6] Deployment example for Buildkite --- website/docs/deployment.mdx | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 98f8f02cfa62..531f6773687e 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -691,6 +691,37 @@ script: Now, whenever a new commit lands in `main`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. +### Triggering deployment with Buildkite {#triggering-deployment-with-buildkite} + +[Buildkite](https://buildkite.com/) is a fast, secure, and reliable continuous integration and continuous delivery platform. + +Follow these steps to create a pipeline that automatically deploys a new version of your website whenever you push changes to your GitHub Pages project. + +1. Sign in to your Buildkite account, select **Pipelines**, then select **New pipeline**. + 1. If this is your first time using Buildkite, you can choose to "Login with GitHub" to connect your GitHub account. + 2. When connected to GitHub, repositories, including ones that use GitHub Pages, automatically populate in the drop-down list. +2. Enter a name and description—or confirm the prepopulated details, if connected to GitHub—then select **Create pipeline**. +3. To run this job, you can set up a local agent or leverage a build runner on your platform of choice. + 1. You can run a [Buildkite agent](https://buildkite.com/docs/agent/v3/installation) locally on your own machine, whether its on a server, virtual private server, desktop computer, or embedded device. +4. Create a a file called `.buildkite/pipeline.yml` in your repository, at root, with the following contents. + 1. You can also choose to define these steps in the Buildkite editor. To do so, select **Settings** from the Pipelines page. + 2. While in repository settings, you can also define custom GitHub settings, including when to trigger builds. + +``` +steps: + - label: ":test_tube: Test" + command: | + yarn + yarn test + + - label: ":hammer: Build" + command: | + yarn + yarn build +``` + +Whenever a new commit lands in `main`, Buildkite will run your suite of tests and if everything passes, your website will be deployed via `yarn test` and `yarn build`, or other custom steps that you choose to define. + ### Triggering deployment with Buddy {#triggering-deployment-with-buddy} [Buddy](https://buddy.works/) is an easy-to-use CI/CD tool that allows you to automate the deployment of your portal to different environments, including GitHub Pages. From 56d7d1d5705d5903edcffc869138e41761d628cb Mon Sep 17 00:00:00 2001 From: Andrew DiMola Date: Thu, 18 Sep 2025 02:33:15 -0400 Subject: [PATCH 2/6] Update deployment instructions for Buildkite --- website/docs/deployment.mdx | 62 +++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 531f6773687e..7d2c0cb7b850 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -695,32 +695,54 @@ Now, whenever a new commit lands in `main`, Travis CI will run your suite of tes [Buildkite](https://buildkite.com/) is a fast, secure, and reliable continuous integration and continuous delivery platform. -Follow these steps to create a pipeline that automatically deploys a new version of your website whenever you push changes to your GitHub Pages project. +Follow these steps to create a pipeline that deploys a new version of your website when you push changes to your GitHub Pages project. -1. Sign in to your Buildkite account, select **Pipelines**, then select **New pipeline**. - 1. If this is your first time using Buildkite, you can choose to "Login with GitHub" to connect your GitHub account. - 2. When connected to GitHub, repositories, including ones that use GitHub Pages, automatically populate in the drop-down list. -2. Enter a name and description—or confirm the prepopulated details, if connected to GitHub—then select **Create pipeline**. -3. To run this job, you can set up a local agent or leverage a build runner on your platform of choice. - 1. You can run a [Buildkite agent](https://buildkite.com/docs/agent/v3/installation) locally on your own machine, whether its on a server, virtual private server, desktop computer, or embedded device. -4. Create a a file called `.buildkite/pipeline.yml` in your repository, at root, with the following contents. - 1. You can also choose to define these steps in the Buildkite editor. To do so, select **Settings** from the Pipelines page. - 2. While in repository settings, you can also define custom GitHub settings, including when to trigger builds. +1. Go to https://github.com/settings/tokens and generate a new personal access token (PAT). When creating the token, grant it the repo scope so that it has the permissions it needs. +2. Set the following fields in `docusaurus.config`. ``` -steps: - - label: ":test_tube: Test" - command: | - yarn - yarn test +url: 'https://$github_username.github.io', +baseUrl: '/', +organizationName: '$github_username', +deploymentBranch: 'gh-pages', +trailingSlash: false, +``` + +3. Configure the GitHub Pages deployment to deploy from the `gh-pages` branch. + 1. Create a new branch titled `gh-pages` (Select **Branch** > **New Branch** > **{New branch name: "gh-pages"}** > **Create new branch**). + 2. Navigate to settings (Select **Settings**). + 3. Navigate to the GitHub Pages settings tab (Select **Pages**). + 4. In the branch drop-down list, change the deployment branch from `main` to `gh-pages`, then press **Save**. +4. Sign in to your [Buildkite](https://buildkite.com/) account, set the `GITHUB_TOKEN` PAT secret, and then create a new pipeline (select **New pipeline**). + 1. Set the repo-scoped PAT that you generated earlier on GitHub as a Buildkite secret. + 1. Set the `key` as `GITHUB_TOKEN`. + 2. Select the GitHub Pages repository. + 3. Select **HTTPS** as the checkout method. + 4. Choose the cluster / agents responsible for executing the pipeline. + 1. You can run a [Buildkite agent](https://buildkite.com/docs/agent/v3/installation) locally on your own machine, whether its on a server, virtual private server, desktop computer, or embedded device. + 5. In the YAML steps editor, copy / paste the following code. When you're finished inserting the YAML steps, select **Create Pipeline**, then select **New Build**. - - label: ":hammer: Build" - command: | - yarn - yarn build ``` +steps: + - label: ":docusaurus: install, build, and deploy" + command: | + git config --global user.name "$${GIT_USER_NAME}" + git config --global user.email "$${GIT_USER_EMAIL}" + yarn install + yarn deploy + plugins: + - secrets#v1.0.0: + variables: + GIT_PASS: GITHUB_TOKEN + env: + GIT_USER: $username + GIT_USER_NAME: "Your Name" + GIT_USER_EMAIL: "Your GitHub Email" +``` + +5. In Buildkite, for some extra emoji fun, you can optionally choose to navigate to Pipeline Settings and select `:docusaurus:` as the Pipeline Emoji. -Whenever a new commit lands in `main`, Buildkite will run your suite of tests and if everything passes, your website will be deployed via `yarn test` and `yarn build`, or other custom steps that you choose to define. +Finished! Whenever a new commit lands in `gh-pages`, your website will be deployed via the `yarn deploy` script. ### Triggering deployment with Buddy {#triggering-deployment-with-buddy} From c959aca0ef848b896cf745bd4111c6c20ccc5f5c Mon Sep 17 00:00:00 2001 From: Andrew DiMola Date: Thu, 18 Sep 2025 02:51:19 -0400 Subject: [PATCH 3/6] Add meta information to code blocks --- website/docs/deployment.mdx | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 7d2c0cb7b850..d273abf35352 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -700,7 +700,7 @@ Follow these steps to create a pipeline that deploys a new version of your websi 1. Go to https://github.com/settings/tokens and generate a new personal access token (PAT). When creating the token, grant it the repo scope so that it has the permissions it needs. 2. Set the following fields in `docusaurus.config`. -``` +```js title="docusaurus.config.js" url: 'https://$github_username.github.io', baseUrl: '/', organizationName: '$github_username', @@ -722,22 +722,22 @@ trailingSlash: false, 1. You can run a [Buildkite agent](https://buildkite.com/docs/agent/v3/installation) locally on your own machine, whether its on a server, virtual private server, desktop computer, or embedded device. 5. In the YAML steps editor, copy / paste the following code. When you're finished inserting the YAML steps, select **Create Pipeline**, then select **New Build**. -``` +```yml title="pipeline.yml" steps: - - label: ":docusaurus: install, build, and deploy" - command: | - git config --global user.name "$${GIT_USER_NAME}" - git config --global user.email "$${GIT_USER_EMAIL}" - yarn install - yarn deploy + - label: ':docusaurus: install, build, and deploy' + command: | + git config --global user.name "$${GIT_USER_NAME}" + git config --global user.email "$${GIT_USER_EMAIL}" + yarn install + yarn deploy plugins: - - secrets#v1.0.0: - variables: - GIT_PASS: GITHUB_TOKEN + - secrets#v1.0.0: + variables: + GIT_PASS: GITHUB_TOKEN env: - GIT_USER: $username - GIT_USER_NAME: "Your Name" - GIT_USER_EMAIL: "Your GitHub Email" + GIT_USER: $username + GIT_USER_NAME: 'Your Name' + GIT_USER_EMAIL: 'Your GitHub Email' ``` 5. In Buildkite, for some extra emoji fun, you can optionally choose to navigate to Pipeline Settings and select `:docusaurus:` as the Pipeline Emoji. From 3a6a93fb92762cdb895185fa1214de6a68a57457 Mon Sep 17 00:00:00 2001 From: Andrew DiMola Date: Thu, 18 Sep 2025 03:13:04 -0400 Subject: [PATCH 4/6] Use parens for MDX safety --- website/docs/deployment.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index d273abf35352..243a9dc7ba81 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -709,7 +709,7 @@ trailingSlash: false, ``` 3. Configure the GitHub Pages deployment to deploy from the `gh-pages` branch. - 1. Create a new branch titled `gh-pages` (Select **Branch** > **New Branch** > **{New branch name: "gh-pages"}** > **Create new branch**). + 1. Create a new branch titled `gh-pages` (Select **Branch** > **New Branch** > **(New branch name: "gh-pages")** > **Create new branch**). 2. Navigate to settings (Select **Settings**). 3. Navigate to the GitHub Pages settings tab (Select **Pages**). 4. In the branch drop-down list, change the deployment branch from `main` to `gh-pages`, then press **Save**. From efc64063b6e4cf126ec72619e316b99e9e52b4b2 Mon Sep 17 00:00:00 2001 From: Christian Nunciato Date: Thu, 18 Sep 2025 12:51:38 -0700 Subject: [PATCH 5/6] Suggestions --- website/docs/deployment.mdx | 90 ++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 243a9dc7ba81..852aea1b60bc 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -695,54 +695,54 @@ Now, whenever a new commit lands in `main`, Travis CI will run your suite of tes [Buildkite](https://buildkite.com/) is a fast, secure, and reliable continuous integration and continuous delivery platform. -Follow these steps to create a pipeline that deploys a new version of your website when you push changes to your GitHub Pages project. +Follow these steps to create a Buildkite pipeline that deploys a new version of your website when you push changes to your GitHub Pages project. -1. Go to https://github.com/settings/tokens and generate a new personal access token (PAT). When creating the token, grant it the repo scope so that it has the permissions it needs. -2. Set the following fields in `docusaurus.config`. +1. Go to https://github.com/settings/tokens and generate a new personal access token (PAT). When creating the token, grant it the `repo` scope so that it has the permissions it needs. +1. Set the following fields in `docusaurus.config`: -```js title="docusaurus.config.js" -url: 'https://$github_username.github.io', -baseUrl: '/', -organizationName: '$github_username', -deploymentBranch: 'gh-pages', -trailingSlash: false, -``` - -3. Configure the GitHub Pages deployment to deploy from the `gh-pages` branch. - 1. Create a new branch titled `gh-pages` (Select **Branch** > **New Branch** > **(New branch name: "gh-pages")** > **Create new branch**). - 2. Navigate to settings (Select **Settings**). - 3. Navigate to the GitHub Pages settings tab (Select **Pages**). - 4. In the branch drop-down list, change the deployment branch from `main` to `gh-pages`, then press **Save**. -4. Sign in to your [Buildkite](https://buildkite.com/) account, set the `GITHUB_TOKEN` PAT secret, and then create a new pipeline (select **New pipeline**). - 1. Set the repo-scoped PAT that you generated earlier on GitHub as a Buildkite secret. - 1. Set the `key` as `GITHUB_TOKEN`. - 2. Select the GitHub Pages repository. - 3. Select **HTTPS** as the checkout method. - 4. Choose the cluster / agents responsible for executing the pipeline. - 1. You can run a [Buildkite agent](https://buildkite.com/docs/agent/v3/installation) locally on your own machine, whether its on a server, virtual private server, desktop computer, or embedded device. - 5. In the YAML steps editor, copy / paste the following code. When you're finished inserting the YAML steps, select **Create Pipeline**, then select **New Build**. - -```yml title="pipeline.yml" -steps: - - label: ':docusaurus: install, build, and deploy' - command: | - git config --global user.name "$${GIT_USER_NAME}" - git config --global user.email "$${GIT_USER_EMAIL}" - yarn install - yarn deploy - plugins: - - secrets#v1.0.0: - variables: - GIT_PASS: GITHUB_TOKEN - env: - GIT_USER: $username - GIT_USER_NAME: 'Your Name' - GIT_USER_EMAIL: 'Your GitHub Email' -``` - -5. In Buildkite, for some extra emoji fun, you can optionally choose to navigate to Pipeline Settings and select `:docusaurus:` as the Pipeline Emoji. + ```js title="docusaurus.config.js" + url: 'https://.github.io', + baseUrl: '/', + organizationName: '', + deploymentBranch: 'gh-pages', + trailingSlash: false, + ``` -Finished! Whenever a new commit lands in `gh-pages`, your website will be deployed via the `yarn deploy` script. +1. Configure the GitHub Pages deployment to deploy from the `gh-pages` branch: + 1. In the GitHub dashboard, create a new branch in your Docusaurus repository titled `gh-pages`. Choose **Branches** > **New Branch**, choose `main` as the source, and **Create new branch**. + 1. Navigate to **Settings** > **Pages**. + 1. In the branch drop-down list, change the deployment branch from `main` to `gh-pages`, then press **Save**. +1. Sign in to your [Buildkite](https://buildkite.com/) account and create a new Buildkite secret and pipeline: + + 1. Navigate to **Secrets** > **New secret**. + 1. Use `GITHUB_TOKEN` for the key and your GitHub PAT for the value, then save. + 1. Navigate to **Pipelines** > **New pipeline**. + + 1. Choose your Docusaurus repository, select **HTTPS** as the checkout method, and leave `main` as the default branch. + 1. Choose a Buildkite agent [cluster](https://buildkite.com/docs/pipelines/clusters) for the pipeline. + 1. In the YAML steps editor, copy and paste the following pipeline YAML. When you're finished, select **Create Pipeline**, then **New Build**. + + ```yml + steps: + - label: ':docusaurus: install, build, and deploy' + command: | + git config --global user.name "$${GIT_USER_NAME}" + git config --global user.email "$${GIT_USER_EMAIL}" + yarn install + yarn deploy + plugins: + - secrets#v1.0.0: + variables: + GIT_PASS: GITHUB_TOKEN + env: + GIT_USER: '' + GIT_USER_NAME: 'Your Name' + GIT_USER_EMAIL: 'Your GitHub Email' + ``` + +1. Optionally, navigate to Pipeline Settings set `:docusaurus:` as your [pipeline emoji](https://buildkite.com/docs/platform/emojis). + +Now, whenever a new commit lands in `main`, your website will be built and pushed to the `gh-pages` branch and published automatically with the `yarn deploy` script. ### Triggering deployment with Buddy {#triggering-deployment-with-buddy} From dfa09856f88b9ce603064b9847ffa0fa944b4903 Mon Sep 17 00:00:00 2001 From: Andrew Date: Thu, 18 Sep 2025 19:03:49 -0400 Subject: [PATCH 6/6] Update website/docs/deployment.mdx Co-authored-by: Christian Nunciato --- website/docs/deployment.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 852aea1b60bc..f638cd9fc1aa 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -740,7 +740,7 @@ Follow these steps to create a Buildkite pipeline that deploys a new version of GIT_USER_EMAIL: 'Your GitHub Email' ``` -1. Optionally, navigate to Pipeline Settings set `:docusaurus:` as your [pipeline emoji](https://buildkite.com/docs/platform/emojis). +1. Optionally, navigate to Pipeline Settings and set `:docusaurus:` as your [pipeline emoji](https://buildkite.com/docs/platform/emojis). Now, whenever a new commit lands in `main`, your website will be built and pushed to the `gh-pages` branch and published automatically with the `yarn deploy` script.