DEVOPS-764 feat: add support for skipping org pool checkout via env var (#12)

* DEVOPS-764 feat: add support for skipping org pool checkout via environment variable

* DEVOPS-764 docs: clarify truthy and falsy values for Clariti checkout in scratch orgs

Author: dipakparmar

cumulusci/core/config/scratch_org_config.py

@@ -99,7 +99,15 @@ def days_alive(self) -> Optional[int]:
     def create_org(self) -> None:
         """Uses sf org create scratch  to create the org"""
         try:
-            if self._try_checkout_pooled_org():
+            if (
+                self.config.get("org_pool_id")
+                and self._should_skip_pool_checkout_env()
+            ):
+                self.logger.info(
+                    "Skipping Clariti org pool checkout because CCI_DISABLE_POOL_CHECKOUT "
+                    "is set."
+                )
+            elif self._try_checkout_pooled_org():
                 return
             if (
                 self.config.get("org_pool_id")
@@ -123,6 +131,10 @@ def create_org(self) -> None:
         finally:
             self._cleanup_tmp_config()
 
+    def _should_skip_pool_checkout_env(self) -> bool:
+        value = os.getenv("CCI_DISABLE_POOL_CHECKOUT", "")
+        return value.lower() in ("1", "true", "yes", "on")
+
     def _create_org_via_sfdx(self) -> None:
         if not self.config_file:
             raise ScratchOrgException(

cumulusci/core/config/tests/test_config_expensive.py

@@ -929,6 +929,43 @@ def test_create_org_falls_back_when_checkout_fails(self, mock_checkout):
 
         config._create_org_via_sfdx.assert_called_once()
 
+    @mock.patch.dict(os.environ, {"CCI_DISABLE_POOL_CHECKOUT": "1"})
+    @mock.patch("cumulusci.core.config.scratch_org_config.checkout_org_from_pool")
+    def test_create_org_skips_pool_checkout_when_disabled(self, mock_checkout):
+        mock_keychain = mock.Mock()
+        mock_keychain.project_config = mock.Mock(project__name="Project")
+        config = ScratchOrgConfig(
+            {
+                "config_file": "tmp.json",
+                "org_pool_id": "Pool42",
+            },
+            "dev",
+            mock_keychain,
+        )
+        config._create_org_via_sfdx = mock.Mock()
+
+        config.create_org()
+
+        config._create_org_via_sfdx.assert_called_once()
+        mock_checkout.assert_not_called()
+
+    @mock.patch("cumulusci.core.config.scratch_org_config.checkout_org_from_pool")
+    def test_create_org_without_pool_id_creates_from_scratch(self, mock_checkout):
+        mock_keychain = mock.Mock()
+        config = ScratchOrgConfig(
+            {
+                "config_file": "tmp.json",
+            },
+            "dev",
+            mock_keychain,
+        )
+        config._create_org_via_sfdx = mock.Mock()
+
+        config.create_org()
+
+        config._create_org_via_sfdx.assert_called_once()
+        mock_checkout.assert_not_called()
+
     @mock.patch("cumulusci.core.config.scratch_org_config.import_sfdx_org_to_keychain")
     @mock.patch("cumulusci.core.config.scratch_org_config.checkout_org_from_pool")
     @mock.patch("cumulusci.core.config.scratch_org_config.set_sf_alias")

docs/scratch-orgs.md

@@ -299,6 +299,22 @@ fresh scratch org if the checkout fails or the pooled org is already expired. Se
 `CCI_DISABLE_SCRATCH_FALLBACK=1` while you debug checkout issues to prevent new
 scratch orgs from being created.
 
+If the pool identifier should remain configured but you want to avoid the
+checkout (for example, because you are creating an org that will later be
+imported into the pool), set `CCI_DISABLE_POOL_CHECKOUT=1` in your environment.
+CumulusCI leaves the pool metadata intact while creating the org from scratch.
+
+### Checkout behavior matrix
+
+| `org_pool_id` | `CCI_DISABLE_POOL_CHECKOUT` | `CCI_DISABLE_SCRATCH_FALLBACK` | Result |
+|--------------:|----------------------------|-------------------------------|--------|
+| not set | any | any | Always creates a scratch org via `sf org create scratch`. |
+| set | truthy | any | Skips Clariti checkout and creates a scratch org. |
+| set | falsy | truthy | Attempts Clariti checkout; failing checkout raises `ScratchOrgException`. |
+| set | falsy | falsy | Attempts Clariti checkout; failing checkout falls back to scratch org creation. |
+
+**Note:** "truthy" values include `1`, `true`, `yes`, or `on` (case-insensitive); "falsy" includes empty string, `0`, `false`, `no`, or `off`.
+
 ## Use a Non-Default Dev Hub
 
 By default, CumulusCI creates scratch orgs using the DevHub org