Merge branch 'main' into DOCSS-1978-chunk-rewrite-open-preview

Author: rosieyohannan

.github/pull_request_template.md

@@ -1,9 +1,8 @@
-
-You may find that there are errors for the `vale/lint` job that are unrelated to your change.
-Vale checks the whole file when a change is made so if there are existing issues on the page they will be flagged.
-
-You can just leave these errors and the CircleCI docs team will address them for you.
-Vale logs are advisory to help all contributors create content that conforms to our style guide. The `vale/lint` job will not prevent changes from being published.
+> [!NOTE]
+> You may find that there are errors for the `vale/lint` job that are unrelated to your change.
+> Vale checks the whole file when a change is made so if there are existing issues on the page they will be flagged.
+> You can ignore lint errors outside your changes and the CircleCI docs team will address them for you.
+> Vale logs are advisory to help all contributors create content that conforms to our style guide. The `vale/lint` job will not prevent changes from being published.
 
 # Description
 What did you change?
@@ -15,17 +14,17 @@ Why did you make these changes? What problem does this solve?
 Please follow our style when contributing to CircleCI docs. View our [style guide](https://circleci.com/docs/style/style-guide-overview) or check out our [CONTRIBUTING.md](../CONTRIBUTING.md) for more information.
 
 **Preview your changes:**
-- To view the Vale linter results, select the `ci/circleci: lint` job at the bottom of your PR. You will be redirected to the `vale/lint` job output in CircleCI.
-- To preview your changes, select the `ci/circleci: build` job at the bottom of your PR and you will be redirected to CircleCI. Select the Artifacts tab and select `index.html` to open a preview version of the docs site built for your latest commit.
+- [ ] View the Vale linter results, select the `ci/circleci: lint` job at the bottom of your PR. You will be redirected to the `vale/lint` job output in CircleCI.
+- [ ] Preview your changes, select the `ci/circleci: build` job at the bottom of your PR and you will be redirected to CircleCI. Select the Artifacts tab and select `index.html` to open a preview version of the docs site built for your latest commit.
 
 Take a moment to check through the following items when submitting your PR (this is just a guide so will not be relevant for all PRs):
 
 **Content structure:**
-- Break up walls of text by adding paragraph breaks.
-- Consider if the content could benefit from more structure, such as lists or tables, to make it easier to consume.
-- Consider whether the content would benefit from more subsections (h2-h6 headings) to make it easier to consume.
-- Include relevant backlinks to other CircleCI docs/pages.
+- [ ] Break up walls of text by adding paragraph breaks.
+- [ ] Consider if the content could benefit from more structure, such as lists or tables, to make it easier to consume.
+- [ ] Consider whether the content would benefit from more subsections (h2-h6 headings) to make it easier to consume.
+- [ ] Include relevant backlinks to other CircleCI docs/pages.
 
 **Formatting:**
-- Keep the title between 20 and 70 characters.
-- Check all headings h1-h6 are in sentence case (only first letter is capitalized).
+- [ ] Keep the title between 20 and 70 characters.
+- [ ] Check all headings h1-h6 are in sentence case (only first letter is capitalized).

docs/guides/modules/test/pages/smarter-testing.adoc

@@ -65,12 +65,12 @@ kubectl -n <namespace> create secret docker-registry regcred \
 [#create-helm-values]
 == 3. Create Helm values
 
-Before installing CircleCI, it is recommended to create a new `values.yaml` file unique to your installation. xref:server-admin:installation:installation-reference.adoc#example-manifests[The Installation Reference section] contains some example `values.yaml` files that are a good place to start. The following describes the minimum required values to include in `values.yaml`. Additional customizations are available, see the provided `values.yaml` for all available options.
+Before installing CircleCI, it is recommended to create a new `values.yaml` file unique to your installation. xref:server-admin:installation:installation-reference.adoc#example-manifests[The Installation Reference Section] contains some example `values.yaml` files that are a good place to start. The following describes the minimum required values to include in `values.yaml`. Additional customizations are available, see the provided `values.yaml` for all available options.
 
 For sensitive data there are two options:
 
-* Add into the `values.yaml` file
-* Add them as Kubernetes Secrets directly
+* Add into the `values.yaml` file.
+* Add them as Kubernetes Secrets directly.
 
 This flexibility allows you to manage Kubernetes Secrets using whichever process you prefer. Whichever option you choose, this sensitive information is stored as a Kubernetes Secret within CircleCI.
 
@@ -79,7 +79,7 @@ NOTE: During the installation process, you may use the following command to gene
 [#api-token]
 === a. API token
 
-The application requires a Kubernetes Secret containing an API token. This API token is used to facilitate internal API communication to api-service. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. There are two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
+The application requires a Kubernetes Secret containing an API token. This API token is used to facilitate internal API communication to the API service. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. You have two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
 
 [tabs]
 ====
@@ -107,15 +107,15 @@ CircleCI creates Secret::
 --
 **Option 2:** CircleCI creates the Kubernetes Secret for you.
 
-CircleCI will create the Kubernetes Secret "api-token" automatically.
+CircleCI will create the Kubernetes Secret `api-token` automatically.
 
 --
 ====
 
 [#session-cookie]
 === b. Session cookie
 
-The application requires a session cookie key Kubernetes Secret, which CircleCI uses to sign session cookies. The Secret must be exactly 16 characters long. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. There are two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
+The application requires a session cookie key Kubernetes Secret, which CircleCI uses to sign session cookies. The Secret must be exactly 16 characters long. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. You have two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
 
 [tabs]
 ====
@@ -151,7 +151,7 @@ CircleCI will create the Kubernetes Secret "session-cookie" automatically.
 [#encryption]
 === c. Encryption
 
-The application requires a Kubernetes Secret containing signing and encryption keysets. These keysets are used to encrypt and sign artifacts generated by CircleCI. These keys were created during the prerequisites phase (xref:server-admin:installation:phase-1-gcp-prerequisites.adoc#encryption-signing-keys[GCP prerequisites], xref:server-admin:installation:phase-1-aws-prerequisites.adoc#encryption-signing-keys[AWS prerequisites]). CircleCI will not be able to recover the values if lost. Depending on how you prefer to manage Kubernetes Secrets, there are two options.
+The application requires a Kubernetes Secret containing signing and encryption keysets. These keysets are used to encrypt and sign artifacts generated by CircleCI. These keys were created during the prerequisites phase (xref:server-admin:installation:phase-1-gcp-prerequisites.adoc#encryption-signing-keys[GCP Prerequisites], xref:server-admin:installation:phase-1-aws-prerequisites.adoc#encryption-signing-keys[AWS Prerequisites]). CircleCI will not be able to recover the values if lost. Depending on how you prefer to manage Kubernetes Secrets, you have two options.
 
 [tabs]
 ====
@@ -188,7 +188,7 @@ keyset:
 
 [#postgres-credentials]
 ==== i. Credentials
-The application requires a Kubernetes Secret containing PostgreSQL credentials.  This is true when using either the internal (default) or an externally hosted instance of PostgreSQL. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.
+The application requires a Kubernetes Secret containing PostgreSQL credentials. This requirement applies when using either the internal (default) or an externally hosted instance of PostgreSQL. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets you have two options.
 
 [tabs]
 ====
@@ -264,7 +264,7 @@ postgresql:
 
 === e. MongoDB credentials
 
-The application requires a Kubernetes Secret containing MongoDB credentials. This is true when using either the internal (default) or an externally hosted instance of MongoDB. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.
+The application requires a Kubernetes Secret containing MongoDB credentials. This requirement applies when using either the internal (default) or an externally hosted instance of MongoDB. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets you have two options.
 
 [tabs]
 ====
@@ -479,7 +479,7 @@ Lets Encrypt::
 --
 *Let's Encrypt*
 
-https://letsencrypt.org/[Let's Encrypt] will request and manage certificates for you.  This is a good option when the load balancer is publicly accessible. The following snippet (using your own email) can be added to `values.yaml`:
+https://letsencrypt.org/[Let's Encrypt] will request and manage certificates for you. Let's Encrypt is a good option when the load balancer is publicly accessible. The following snippet (using your own email) can be added to `values.yaml`:
 
 [source,yaml]
 ----
@@ -649,11 +649,11 @@ github:
 === l. Object storage
 
 ifndef::env-gcp[]
-Regardless of your storage provider, the bucket name you xref:server-admin:installation:phase-1-aws-prerequisites.adoc#object-storage-and-permissions[created during the prerequisites phase] will need to be included.
+Regardless of your storage provider, the bucket name you xref:server-admin:installation:phase-1-aws-prerequisites.adoc#object-storage-and-permissions[Created During the Prerequisites Phase] will need to be included.
 endif::env-gcp[]
 
 ifndef::env-aws[]
-Regardless of your storage provider, the bucket name you xref:server-admin:installation:phase-1-gcp-prerequisites.adoc#object-storage-and-permissions[created during the prerequisites phase] will need to be included.
+Regardless of your storage provider, the bucket name you xref:server-admin:installation:phase-1-gcp-prerequisites.adoc#object-storage-and-permissions[Created During the Prerequisites Phase] will need to be included.
 endif::env-aws[]
 
 [source,yaml]
@@ -719,7 +719,7 @@ object_storage:
 ----
 
 **Disable Presigned Mode (Optional)**
-If you wish to store artifacts larger than 5GB, you will need to xref:installation:phase-1-aws-prerequisites.adoc#s3-storage[update your trust policy for your IRSA role]. Then disable presigned mode by adding the following to the `object_storage.s3` section:
+If you wish to store artifacts larger than 5GB, you will need to xref:installation:phase-1-aws-prerequisites.adoc#s3-storage[Update Your Trust Policy for Your IRSA Role]. Then disable presigned mode by adding the following to the `object_storage.s3` section:
 
 [source,yaml]
 ----
@@ -814,11 +814,11 @@ kubectl -n <namespace> create secret generic object-storage-secret \
 endif::env-aws[]
 
 === m. Installing behind a proxy
-Depending on your security requirements, you might want to install CircleCI server behind a proxy. Installing behind a proxy gives you the power to monitor and control access between your installation and the broader Internet. For further information including limitations of installation behind a proxy, see the xref:server-admin:installation:installing-server-behind-a-proxy.adoc#[Installing server behind a proxy] guide.
+Depending on your security requirements, you might want to install CircleCI server behind a proxy. Installing behind a proxy gives you the power to monitor and control access between your installation and the broader Internet. For further information including limitations of installation behind a proxy, see the xref:server-admin:installation:installing-server-behind-a-proxy.adoc#[Installing Server Behind a Proxy] guide.
 
 The following fields need to be configured in your `values.yaml`:
 
-* Toggle `proxy.enabled` to `"1"`
+* Toggle `proxy.enabled` to `"1"`.
 * Enter details for `proxy.http.host` and `proxy.https.host`, along with their associated ports. These values can be the same but they both need to be configured.
 * For authentication you will need to configure `proxy.http.auth.enabled` and `proxy.https.auth.enabled` as `"1"`. You will also need to configure the respective username and password for both HTTP and HTTPS.
 * configure the `no_proxy` hosts and subnets. This should include localhost, your GitHub Enterprise host (optional), the hostname of your CircleCI installation (see xref:server-admin:installation:installing-server-behind-a-proxy.adoc#known-limitations[Known Limitations] for an explanation), and the CIDR of Nomad.
@@ -920,13 +920,13 @@ WARNING: If your Tink keyset is somehow lost, you will need to generate a new ke
 
 === o. Setting up OIDC (optional)
 
-CircleCI server optionally supports xref:guides:permissions-authentication:openid-connect-tokens.adoc#[OpenID Connect (OIDC) tokens] in jobs.
+CircleCI server optionally supports xref:guides:permissions-authentication:openid-connect-tokens.adoc#[Using OpenID Connect Tokens in Jobs] in jobs.
 
 This feature is not enabled by default and requires a few additional steps to set up, as follows:
 
 . Generate a https://mkjwk.org/[JSON Web Key (JWK)] using the default parameters and copy the `Public and Private Keypair Set` to a secure and convenient location (for example, `~/oidc-service-jwk.json`). This key pair will be used by `oidc-service` to sign the OIDC tokens used in jobs.
 
-. The JWK will need to be base64 encoded without line wrapping before using it on server:
+. The JWK will need to be base64 encoded without line wrapping before using it on server.
 ** On Linux:
 +
 [source,shell]
@@ -962,7 +962,7 @@ USERNAME=<provided-username>
 PASSWORD=<token>
 namespace=<your-namespace>
 helm registry login cciserver.azurecr.io/circleci-server -u $USERNAME -p $PASSWORD
-helm install circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version {serverversion47} -f <path-to-values.yaml>
+helm install circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version {serverversion48} -f <path-to-values.yaml>
 ----
 
 [#create-dns-entry]