From 835a446d5f33451820e99effbd09c13ea8bf08f9 Mon Sep 17 00:00:00 2001 From: Anthony Castro Date: Tue, 16 Sep 2025 23:08:27 -0400 Subject: [PATCH 1/4] Update checkout step with method key --- .../ROOT/pages/configuration-reference.adoc | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index 299e748c4b..27fbaa2ca0 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -1667,33 +1667,17 @@ workflows: [#checkout] === *`checkout`* -**** -*Blobless clones* - -A "blobless" strategy is being rolled out to help improve the performance of code checkouts from Git source code hosts. - -Blobless clones reduce the amount of data fetched from the remote, by asking the remote to filter out objects that are not attached to the current commit. - -While this improves performance in most cases, if a downstream step requires those objects to exist for scanning or comparisons, it can cause failures. To work around these potential problems, a fetch directly after a checkout will ensure the required data is available: - -[,yml] ----- -jobs: - build: - docker: - - image: cimg/go:1.24.2 - steps: - - checkout - - run: git fetch ----- -**** - A special step used to check out source code to the configured `path` (defaults to the `working_directory`). The reason this is a special step is because it is more of a helper function designed to simplify the process of checking out code. If you require doing git over HTTPS you should not use this step as it configures git to checkout over SSH. [cols="1,1,1,2", options="header"] |=== | Key | Required | Type | Description +| `method` +| N +| String +| Checkout method. Valid options include `blobless` and `full`. (default: `full`) + | `path` | N | String @@ -1721,6 +1705,39 @@ jobs: The checkout command automatically adds the required authenticity keys for interacting with GitHub and Bitbucket over SSH. These keys are detailed further in the xref:guides:integration:github-integration.adoc#establish-the-authenticity-of-an-ssh-host[integration guide]. This guide is also helpful if you wish to implement a custom checkout command. +By default, the `checkout` step performs a full clone of the source code. You can specify a different checkout strategy by using the `method` key. In addition to full clones, we also support blobless clones. Blobless clones reduce the amount of data fetched from the remote by asking the remote to filter out objects that are not attached to the current commit. + +*Example:* + +[,yml] +---- +jobs: + build: + docker: + - image: cimg/go:1.24.2 + steps: + - checkout: + method: blobless +---- + +[NOTE] +==== +In certain cases, we will fall back to a full checkout even though blobless was specified. This will occur if Git and SSH clients are not available in the current environment, or if Git version 2.41.0 is installed which contained a link:https://lore.kernel.org/git/kl6lh6qyrnjm.fsf@chooglen-macbookpro.roam.corp.google.com/[known issue] for blobless clones. +==== + +If a downstream step requires those objects to exist for scanning or comparisons, a blobless clone can cause failures. In that case, you can specify a full checkout as shown in the following example: + +[,yml] +---- +jobs: + build: + docker: + - image: cimg/go:1.24.2 + steps: + - checkout: + method: full +---- + CircleCI does not check out submodules. If your project requires submodules, add `run` steps with appropriate commands as shown in the following example: [,yml] From 42f6629046c1979f27760d768bbd128fd4a15bc2 Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Fri, 19 Sep 2025 10:08:00 +0100 Subject: [PATCH 2/4] fix some linter errors --- docs/guides/modules/orchestrate/pages/pipeline-variables.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc b/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc index 3605146c81..e354c32966 100644 --- a/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc +++ b/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc @@ -116,7 +116,7 @@ Refer to the xref:toolkit:api-developers-guide.adoc#getting-started-with-the-api [#passing-parameters-when-triggering-pipelines-using-the-circleci-web-app] === Passing parameters when triggering pipelines using the CircleCI web app -In addition to using the API, you can also trigger a pipeline with parameters from the CircleCI web app. If you pass a parameter when triggering a pipeline from the web app, and the parameter has not been declared in the configuration file, the pipeline will fail with the error `Unexpected argument(s)`. +In addition to using the API, you can also trigger a pipeline with parameters from the CircleCI web app. If you pass a parameter when triggering a pipeline, and the parameter has not been declared in the configuration file, the pipeline will fail with the error `Unexpected argument(s)`. . Use the project filter to select the desired project. . Use the branch filter to select the branch on which you want to run the new pipeline. @@ -140,7 +140,7 @@ The remaining configuration is processed, element parameters are resolved, type- [#the-scope-of-parameters-in-configuration] == The scope of parameters in configuration -Pipeline parameters can only be resolved in the `.circleci/config.yml` file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your `.circleci/config.yml` file. This is because access to pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling configuration. This would potentially create a surface area of vulnerability, increasing security risks. +Pipeline parameters can only be resolved in the `.circleci/config.yml` file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your `.circleci/config.yml` file. Access to pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling configuration. This would potentially create a surface area of vulnerability, increasing security risks. [#element-parameter-scope] === Element parameter scope From 7eb6c5e1aa0c5369e175e4fa90ba287a42181af6 Mon Sep 17 00:00:00 2001 From: Anthony Castro Date: Fri, 19 Sep 2025 09:09:39 -0400 Subject: [PATCH 3/4] Update docs/reference/modules/ROOT/pages/configuration-reference.adoc Co-authored-by: Rosie Yohannan --- docs/reference/modules/ROOT/pages/configuration-reference.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index 27fbaa2ca0..cbd4a91e65 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -1705,7 +1705,7 @@ jobs: The checkout command automatically adds the required authenticity keys for interacting with GitHub and Bitbucket over SSH. These keys are detailed further in the xref:guides:integration:github-integration.adoc#establish-the-authenticity-of-an-ssh-host[integration guide]. This guide is also helpful if you wish to implement a custom checkout command. -By default, the `checkout` step performs a full clone of the source code. You can specify a different checkout strategy by using the `method` key. In addition to full clones, we also support blobless clones. Blobless clones reduce the amount of data fetched from the remote by asking the remote to filter out objects that are not attached to the current commit. +You can specify a different checkout strategy by using the `method` key. CircleCI supports full clones or blobless clones. Blobless clones reduce the amount of data fetched from the remote by asking the remote to filter out objects that are not attached to the current commit. *Example:* From 416fa3863984b0768cea71d65883931a249489cc Mon Sep 17 00:00:00 2001 From: Anthony Castro Date: Fri, 19 Sep 2025 09:12:49 -0400 Subject: [PATCH 4/4] Update docs/reference/modules/ROOT/pages/configuration-reference.adoc Co-authored-by: Rosie Yohannan --- docs/reference/modules/ROOT/pages/configuration-reference.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index cbd4a91e65..ff363fc3b8 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -1705,7 +1705,7 @@ jobs: The checkout command automatically adds the required authenticity keys for interacting with GitHub and Bitbucket over SSH. These keys are detailed further in the xref:guides:integration:github-integration.adoc#establish-the-authenticity-of-an-ssh-host[integration guide]. This guide is also helpful if you wish to implement a custom checkout command. -You can specify a different checkout strategy by using the `method` key. CircleCI supports full clones or blobless clones. Blobless clones reduce the amount of data fetched from the remote by asking the remote to filter out objects that are not attached to the current commit. +You can specify a checkout strategy by using the `method` key. CircleCI supports full clones or blobless clones. Blobless clones reduce the amount of data fetched from the remote by asking the remote to filter out objects that are not attached to the current commit. *Example:*