add a warning when regenerating the lockfile for packages

do not include env vars when hashing packages

add changie

Author: Tobie Tusing

.changes/unreleased/Fixes-20250823-155551.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: Fixes issue with package locking, where using environment variables would cause lockfile regeneration in different environments
+time: 2025-08-23T15:55:51.916929-07:00
+custom:
+    Author: ttusing
+    Issue: "11953"

core/dbt/contracts/project.py

@@ -78,13 +78,27 @@ class GitPackage(Package):
     subdirectory: Optional[str] = None
     unrendered: Dict[str, Any] = field(default_factory=dict)
     name: Optional[str] = None
+    exclude_env_vars_from_hash: Optional[bool] = field(
+        default=None, metadata={"alias": "exclude-env-vars-from-hash"}
+    )
 
     def get_revisions(self) -> List[str]:
         if self.revision is None:
             return []
         else:
             return [str(self.revision)]
 
+    def to_dict_for_hash(self) -> Dict[str, Any]:
+        """Create a dict representation for hash calculation that can optionally exclude env vars"""
+        data = self.to_dict()
+        if self.exclude_env_vars_from_hash:
+            # Use unrendered git URL if available to exclude env vars from hash
+            if "git" in self.unrendered:
+                data["git"] = self.unrendered["git"]
+            # Remove the exclude-env-vars-from-hash flag itself from the hash
+            data.pop("exclude-env-vars-from-hash", None)
+        return data
+
 
 @dataclass
 class PrivatePackage(Package):

core/dbt/events/types.py

@@ -1517,6 +1517,14 @@ def message(self) -> str:
         return f"Found duplicate package in packages.yml, removing: {self.removed_package}"
 
 
+class DepsLockfileRegenerating(WarnLevel):
+    def code(self):
+        return "M034"
+
+    def message(self) -> str:
+        return f"Package lockfile is out of sync with packages.yml. Regenerating lockfile at: {self.lock_filepath}"
+
+
 class DepsScrubbedPackageName(WarnLevel):
     def code(self):
         return "M035"

core/dbt/task/deps.py

@@ -21,6 +21,7 @@
     DepsFoundDuplicatePackage,
     DepsInstallInfo,
     DepsListSubdirectory,
+    DepsLockfileRegenerating,
     DepsLockUpdating,
     DepsNoPackagesFound,
     DepsNotifyUpdatesAvailable,
@@ -50,7 +51,14 @@ def _create_sha1_hash(packages: List[PackageSpec]) -> str:
     Returns:
         str: SHA1 hash of the packages list
     """
-    package_strs = [json.dumps(package.to_dict(), sort_keys=True) for package in packages]
+    package_strs = []
+    for package in packages:
+        if hasattr(package, "to_dict_for_hash"):
+            package_dict = package.to_dict_for_hash()
+        else:
+            package_dict = package.to_dict()
+        package_strs.append(json.dumps(package_dict, sort_keys=True))
+
     package_strs = sorted(package_strs)
 
     return sha1("\n".join(package_strs).encode("utf-8")).hexdigest()
@@ -220,6 +228,7 @@ def run(self) -> None:
             current_hash = _create_sha1_hash(self.project.packages.packages)
             previous_hash = load_yml_dict(lock_file_path).get(PACKAGE_LOCK_HASH_KEY, None)
             if previous_hash != current_hash:
+                fire_event(DepsLockfileRegenerating(lock_filepath=lock_file_path))
                 self.lock()
 
         # Early return when 'dbt deps --lock'