Merge branch 'main' into fix-responsive-wide-content

Author: rosieyohannan

docs/guides/modules/config-policies/pages/config-policy-management-overview.adoc

@@ -155,9 +155,6 @@ input.workflows     # an array of nested structures mirroring workflows in the C
 input.jobs          # an array of nested structures mirroring jobs in the CircleCI config
 ----
 
-[#define-a-rule]
-==== Define a rule
-
 In OPA, rules can produce any type of output. At CircleCI, rules that produce violations must have outputs of the following types:
 
 * String
@@ -168,7 +165,7 @@ This restriction is in place so that rule violations produce error messages that
 Helper rules that produce differently typed outputs can still be defined, but rules that will be considered when making CircleCI decisions must have the output types specified above. For more information see the <<#enablement>> section below.
 
 [#evaluation]
-===== Evaluation
+==== Evaluation
 
 Evaluation is how the decision engine determines if a config violates the given policy. The evaluation defines the name and ID of the rule, checks a condition, and returns a user-friendly string describing the violation. Rule evaluations include the **rule name** and an **optional rule ID**. The rule name will be used to enable and set the enforcement level for a rule.
 
@@ -217,7 +214,7 @@ docker_images := {image | walk(input, [path, value])  # walk the entire config t
 ----
 
 [#enforcement]
-===== Enforcement
+==== Enforcement
 
 The policy service allows rules to be enforced at different levels.
 
@@ -239,7 +236,7 @@ hard_fail["use_official_docker_image"]
 ----
 
 [#enablement]
-===== Enablement
+==== Enablement
 
 A rule must be enabled for it to be inspected for policy violations. Rules that are not enabled do not need to match CircleCI violation output formats, and can be used as helpers for other rules.
 

docs/guides/modules/deploy/pages/deployment-overview.adoc

@@ -187,14 +187,12 @@ Labels are composed of two values separated by a colon, for example, `team:my-te
 
 Once you have added labels to your components and environments, you can use them to filter your view in the deploys UI. In the timeline, environments, or components view, select a filter to reduce the content in the tab to only your selection. You can also use the label filter dropdown menu at the top of the page.
 
-==== Add or edit labels
-
 To add or edit labels follow the steps below.
 
 .Add and Edit environment and component labels
 image::guides:ROOT:releases/edit-labels.png[Screenshot showing the location of the add/edit labels button]
 
-===== Component labels
+==== Component labels
 
 To add or edit labels for a component, follow these steps:
 
@@ -204,7 +202,7 @@ To add or edit labels for a component, follow these steps:
 . You are now on the component view page. Select the edit button image:guides:ROOT:icons/edit-solid.svg[edit icon, role="no-border"] in the labels panel.
 . Enter or edit your label(s) and select btn:[Done].
 
-===== Environment labels
+==== Environment labels
 
 To add or edit labels for an environment, follow these steps:
 

docs/guides/modules/execution-managed/pages/remote-docker-images-support-policy.adoc

@@ -11,7 +11,8 @@ This document outlines the xref:building-docker-images.adoc[CircleCI remote Dock
 [#release-policy]
 == Release policy
 
-The CircleCI remote Docker images are based on our Linux VM images with Docker installed for the purposes of providing a remote environment that can execute Docker commands within jobs on the Docker executor.
+The CircleCI remote Docker images are based on our Linux VM images with Docker installed.
+This setup enables the execution of Docker commands within jobs using the Docker executor in a remote environment.
 
 We aim to support the latest three versions of the Docker Engine that are classified as within Security Support status.
 
@@ -33,7 +34,7 @@ For the previous major version of Docker, we support a single tag following the
 [#critical-cve-patches]
 == Critical CVE patches
 
-When critical CVEs are disclosed around the operating system or software stack of this image, we will investigate the impact this has on the image within the CircleCI execution environment. If customers are impacted by these CVEs we will push a patch fix to the released image(s), this image will supersede the original image.
+When critical CVEs are disclosed around the operating system or software stack of this image, we will investigate the impact this has on the image within the CircleCI execution environment. If customers are impacted by these CVEs we will push a patch fix to the released image(s), this image will supersede the original image. These patches will not include major OS updates. Patches will contain only patch OS updates.
 
 [#bug-reports-issues-and-prs]
 == Bug reports, issues, and PRs
@@ -64,6 +65,11 @@ Current Deprecation:
 
 Example: When Docker 28 is released:
 
+We have delayed upgrading to Docker 28 because early releases introduced networking changes that caused instability in some environments.
+Rather than risk disruption for our customers, we chose to stay on the stable and supported 27.x line while monitoring the maturity of 28.
+With the release of 28.3.3, the previous issues appear to have been resolved.
+We are now preparing to validate and roll out the upgrade to ensure a smooth transition.
+
 [cols="1,2", options="header"]
 |===
 | Version

docs/guides/modules/execution-runner/pages/container-runner.adoc

@@ -198,7 +198,7 @@ Image match types govern how images are matched for container customization. The
 
 * *Default:* The `Default` match type applies when an image did not match any of the other image match types. It sets a single specification for all such service containers.
 
-===== Order of precedence
+==== Order of precedence
 
 Selectors follow the hierarchy: `Exact` -> `Prefix` -> `Pattern` -> `Default`. If a given image name does not match any rule in the hierarchy, it defaults to the `Default` rule.
 
@@ -237,7 +237,7 @@ agent:
             memory: "200Mi"
 ----
 
-===== Order of precedence
+==== Order of precedence
 
 The `Resource class` scope overrides any `Global` scope selection for a given match type. If a match is available in both scopes, the `Resource class` scope prevails.
 

docs/guides/modules/execution-runner/pages/runner-api.adoc

@@ -65,7 +65,7 @@ Lists the available self-hosted runners based on the specified parameters. It is
 ** This allows the endpoint to be accessible on circleci.com/api/v3/runner for users that have already logged into circleci.com
 
 [#get-api-v3-runner-request]
-===== Request
+==== Request
 
 [cols=5*, options="header"]
 |===

docs/guides/modules/execution-runner/pages/runner-upgrading-on-server.adoc

@@ -88,27 +88,42 @@ Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManage
 
 The currently running `circleci-launch-agent` process will need to be halted before starting the newly updated binary. Platform-specific instructions for this are given below.
 
-[#stopping-the-machine-runner-on-linux]
-===== Stopping the machine runner on Linux
-
+[tabs]
+====
+Linux::
++
+--
 Run the following commands:
 
 ```shell
 sudo systemctl stop circleci.service
 sudo systemctl disable circleci.service
 ```
+--
+Mac::
++
+--
+Run the following command:
 
-[#stopping-the-machine-runner-on-mac]
-===== Stopping the machine runner on Mac
-
-Run the following commands:
 
 ```shell
 sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'
 ```
+--
+Windows::
++
+--
+Run the following command:
+
+
+``` powershell
+Stop-ScheduledTask -TaskName "CircleCI Launch Agent"
+```
+--
+====
 
 [#stopping-the-machine-runner-on-windows]
-===== Stopping the machine runner on Windows
+==== Stopping the machine runner on Windows
 
 Run the following command:
 
@@ -121,34 +136,38 @@ Stop-ScheduledTask -TaskName "CircleCI Launch Agent"
 
 Platform-specific instructions are given below.
 
-[#starting-on-linux]
-===== Starting on Linux
-
+[tabs]
+====
+Linux::
++
+--
 Run the following commands:
 
 ```shell
 sudo systemctl reload circleci.service
 sudo systemctl enable circleci.service
 sudo systemctl start circleci.service
 ```
-
-[#starting-on-mac]
-===== Starting on Mac
-
+--
+Mac::
++
+--
 Run the following command:
 
 ```shell
 sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist'
 ```
-
-[#starting-on-windows]
-===== Starting on Windows
-
-Run the following commands:
+--
+Windows::
++
+--
+Run the following command:
 
 ``` powershell
 Start-ScheduledTask -TaskName "CircleCI Launch Agent"
 ```
+--
+====
 
 [#additional-resources]
 === Additional resources

docs/guides/modules/optimize/pages/use-the-circleci-cli-to-split-tests.adoc

@@ -62,7 +62,7 @@ Two commands are available for you to split your tests. We recommend using `circ
 Alternatively, you can see `circleci tests split` examples <<tests-split-examples,here>>
 
 [#tests-run-examples]
-==== Test framework examples using `circleci tests run`
+== Test framework examples using circleci tests run
 
 The following set of examples show how to use the `circelci tests run` command to split and run your tests across parallel execution environments. Using this command also allows you to use the xref:test:rerun-failed-tests.adoc[rerun failed tests] feature.
 
@@ -76,7 +76,7 @@ Some notes on the examples below:
 * If you do not use `store_test_results`, there will be no timing data available to split your tests.
 
 [#ruby-rspec-tests]
-===== Ruby (RSpec)
+=== Ruby (RSpec)
 
 . Add the following gem to your Gemfile:
 +
@@ -108,7 +108,7 @@ jobs:
 ** Update the `glob` command to match your use case. See the RSpec section in the xref:test:collect-test-data.adoc#rspec[Collect Test Data] document for details on how to output test results in an acceptable format for `rspec`.
 
 [#configure-a-job-running-ruby-cucumber-tests]
-===== Ruby (Cucumber)
+=== Ruby (Cucumber)
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 
@@ -133,7 +133,7 @@ jobs:
 * Update the `glob` command to match your use case. See the Cucumber section in the xref:test:collect-test-data.adoc#cucumber[Collect Test Data] document for details on how to output test results in an acceptable format for `Cucumber`.
 
 [#cypress-tests]
-===== Cypress
+=== Cypress
 
 . Use the link:https://www.npmjs.com/package/cypress-circleci-reporter[`cypress-circleci-reporter`] (this is a 3rd party tool that is not maintained by CircleCI).  You can install the tool in your `.circleci/config.yml` or add to your `package.json`. Example for adding to `.circleci/config.yml`:
 +
@@ -178,7 +178,7 @@ jobs:
 ** Cypress may output a warning: `Warning: It looks like you're passing --spec a space-separated list of arguments:`.  This can be ignored, but it can be removed by following the guidance from our link:https://discuss.circleci.com/t/product-launch-re-run-failed-tests-only-circleci-tests-run/47775/18[community forum].
 
 [#javascript-typescript-jest-tests]
-===== JavaScript/TypeScript (Jest)
+=== JavaScript/TypeScript (Jest)
 
 . Install the `jest-junit` dependency. You can add this step in your `.circleci/config.yml`:
 +
@@ -217,7 +217,7 @@ jobs:
 ** `JEST_JUNIT_ADD_FILE_ATTRIBUTE=true` is added to ensure that the `file` attribute is present. `JEST_JUNIT_ADD_FILE_ATTRIBUTE=true` can also be added to your `jest.config.js` file instead of including it in `.circleci/config.yml`, by using the following attribute: `addFileAttribute="true"`.
 
 [#playwright-tests]
-===== Playwright
+=== Playwright
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 
@@ -246,7 +246,7 @@ jobs:
 * Ensure that you are using version 1.34.2 or later of Playwright. Earlier versions of Playwright may not output JUnit XML in a format that is compatible with this feature.
 
 [#kotlin-or-gradle-tests]
-===== Kotlin or Gradle
+=== Kotlin or Gradle
 
 . Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 +
@@ -280,7 +280,7 @@ jobs:
 . Update the `glob` command to match your use case.
 
 [#configure-a-job-running-go-tests]
-===== Go
+=== Go
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 
@@ -302,7 +302,7 @@ jobs:
 * Ensure you are using `xargs` in your `circleci tests run` command to pass the list of test files/classnames via stdin to `--command`.
 
 [#elixir-tests]
-===== Elixir
+=== Elixir
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 
@@ -332,7 +332,7 @@ jobs:
 * Update the `glob` command to match your use case.
 
 [#configure-a-job-running-phpunit-tests]
-===== PHPUnit
+=== PHPUnit
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`:
 
@@ -362,7 +362,7 @@ jobs:
 * Note that this example uses a utility named link:https://github.com/previousnext/phpunit-finder[`phpunit-finder`] which is a third party tool that is not supported by CircleCI, use at your own risk.
 
 [#configure-django-tests]
-===== Django
+=== Django
 
 Modify your CircleCI configuration file to specify parallelism, and update your test command to use `circleci tests run`. Also, Django takes as input test filenames with a format that uses dots ("."), however, it outputs JUnit XML in a format that uses slashes "/".  To account for this, get the list of test filenames first, change the filenames to be separated by dots "." instead of slashes "/", and pass the filenames into the test command.
 
@@ -393,7 +393,7 @@ jobs:
 . Ensure you are using `xargs` in your `circleci tests run` command to pass the list of test files/classnames via stdin to `--command`.
 
 [#output-test-files-only]
-===== Output test files only
+=== Output test files only
 
 If your testing set-up on CircleCI is not compatible with invoking your test runner in the `circleci tests run` command, you can opt to use `circleci tests run` to:
 
@@ -520,7 +520,7 @@ The available timing data will then be analyzed and your tests will be split acr
 NOTE: If no timing data is found, you will receive a message: `Error auto-detecting timing type, falling back to weighting by name.`. The tests will then be split alphabetically by test name.
 
 [#set-the-timing-type]
-===== Set the timing type
+=== Set the timing type
 
 The environment CLI attempts to autodetect the granularity of the test split (for example, whether to split by filename, or down to class name) based on the input. You may need to choose a different timing type depending on how your test coverage output is formatted, using the `--timings-type` option. Valid timing types are:
 
@@ -534,7 +534,7 @@ cat my_java_test_classnames | circleci tests split --split-by=timings --timings-
 ```
 
 [#set-the-default-value-for-missing-timing-data]
-===== Set the default value for missing timing data
+=== Set the default value for missing timing data
 
 For partially found test results, any tests with missing data are assigned a random small value. You can override this default value with the `--time-default` flag:
 
@@ -543,7 +543,7 @@ circleci tests glob "**/*.rb" | circleci tests split --split-by=timings --time-d
 ```
 
 [#download-timing-data]
-===== Download timing data
+=== Download timing data
 
 If you need to manually store and retrieve timing data, add the xref:reference:ROOT:configuration-reference.adoc#storeartifacts[`store_artifacts` step] to your job.
 

docs/guides/modules/orchestrate/pages/github-trigger-event-options.adoc

@@ -50,6 +50,7 @@ GitHub App triggers allow you to define the work to do (pipeline) when an event
 * *PR opened or pushed to, default branch and tag pushes*: Trigger a pipeline on pushes to a branch for which there is an open Pull Request (PR), when a PR is opened, pushes to any tag, and pushes to the default branch. This applies also if the PR is re-opened after being closed.
 * *PR opened*: Trigger a pipeline when a PR is opened. This applies also if the PR has been opened in draft. It does not apply if the PR is closed and then re-opened. See the link:https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=opened#pull_request[GitHub docs for the pull request opened event].
 * *PR merged*: Trigger a pipeline when a PR is merged only. See the link:https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=closed#pull_request[GitHub docs for pull request closed].
+* *PR merged or closed*: Trigger a pipeline when a PR is merged or closed. When this option is selected, pipelines will run by default on the _base_ branch on the pull request, not on the _head_ branch.
 * *PR marked ready for review*: Trigger a pipeline when a PR is taken out of draft mode and marked ready for review. See the link:https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=review_requested#pull_request[GitHub docs for pull request review requested].
 * *"run-ci" label added to PR*: Trigger a pipeline when a label "run-ci" is added to a PR. See the link:https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=labeled#pull_request[GitHub docs for pull request labelled].
 * *Pushes to open non-draft PRs*: Trigger a pipeline when there is a push to a branch with an open PR that is not in draft mode.

docs/guides/modules/permissions-authentication/pages/openid-connect-tokens.adoc

@@ -216,7 +216,7 @@ workflows:
 You can take advantage of the format of the claims in CircleCI's <<format-of-the-openid-connect-id-token,OIDC token>> to limit what your CircleCI jobs can do in AWS.
 
 [#limit-role-access-based-on-project]
-===== Limit role access based on project
+=== Limit role access based on project
 
 If certain projects should only be able to access certain AWS resources, you can restrict your IAM role so that only CircleCI jobs in a specific project can assume that role.
 
@@ -235,7 +235,7 @@ To do this, edit your IAM role's trust policy so that only an OIDC token from yo
 This uses https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String[StringLike] to match the sub claim of CircleCI's OIDC token in your chosen project. Now, jobs in your other projects cannot assume this role.
 
 [#limit-role-access-based-on-branch]
-===== Limit role access based on branch
+=== Limit role access based on branch
 
 You can also restrict access to specific branches. The following is an example of a trust policy that restricts the `AssumeRoleWithWebIdentity` action to any project pipelines running only on the `main` branch in the `my-org` GitHub organization and the CircleCI organization with the ID: `organization_id`. Note that the `sub` claim uses the `$CIRCLE_OIDC_TOKEN_V2` format.