circleci · rosieyohannan · Sep 11, 2025 · Sep 10, 2025 · Sep 10, 2025 · Sep 11, 2025
@@ -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.
 

@@ -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:
 

@@ -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.
 

@@ -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"]
 |===

@@ -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

@@ -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.
 

@@ -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.
 

@@ -109,7 +109,7 @@ For more information, including an example, see the xref:permissions-authenticat
 
 A subcommand of `run`. The `circleci run release` commands allow you to manage your deployments.
 
-===== Plan
+==== Plan
 
 A subcommand of `release`. The `circleci run release plan` command is used to plan and identify a new deployment that will be referenced in the CircleCI UI. When a release is planned you can then update its status later in your pipeline to track progress of a deployment.
 
@@ -154,7 +154,7 @@ jobs:
 
 For more information on using the `circleci run release plan` command, see the xref:deploy:configure-deploy-markers.adoc[Configure deploy markers] page.
 
-===== Update
+==== Update
 
 WARNING: The `circleci run release update` command is only for use with deploy markers. If you are using the CircleCI xref:deploy:release-agent-overview.adoc[release agent] for Kubernetes deployments, do NOT use the `update` commands. The release agent automatically handles status updates for you.
 
@@ -187,7 +187,7 @@ jobs:
 
 For more information on using the `circleci run release update` command, see the xref:deploy:configure-deploy-markers.adoc[Configure deploy markers] page.
 
-===== Log
+==== Log
 
 A subcommand of `release`. The `circleci run release log` command allows you to log your deployments without status updates