Nov 9, 2025 · Nov 8, 2025 · Nov 8, 2025 · Nov 8, 2025 · Nov 2, 2025 · Nov 8, 2025
diff --git a/docs/configuration/automatic-releases/github-actions.rst b/docs/configuration/automatic-releases/github-actions.rst
          contents: write

        steps:
          # Note: We checkout the repository at the branch that triggered the workflow
          #with the entire history to ensure to match PSR's release branch detection
          #andhistory evaluation.
          #However, we forcefully reset thebranch to the workflow sha because it is
          #possible thatthebranch wasupdated while the workflow was running. This
          #prevents accidentally releasing un-evaluatedchanges.
          # Note: We checkout the repository at the branch that triggered the workflow.
          #Python Semantic Release will automatically convert shallow clones to full clones
          #if needed to ensure properhistory evaluation. However, we forcefully reset the
          # branch to the workflow sha because it is possible that the branch was updated
          #whiletheworkflow wasrunning, which prevents accidentally releasing un-evaluated
          # changes.
          - name: Setup | Checkout Repository on Release Branch
            uses: actions/checkout@v4
            with:
              ref: ${{ github.ref_name }}
              fetch-depth: 0

          - name: Setup | Force release branch to be at workflow sha
            run: |
  one release job in the case if there are multiple pushes to ``main`` in a short period
  of time.

 .. warning::
  You must set ``fetch-depth`` to 0 when using ``actions/checkout@v4``, since
  Python Semantic Release needs access to the full history to build a changelog
  and at least the latest tags to determine the next version.

 .. warning::
  The ``GITHUB_TOKEN`` secret is automatically configured by GitHub, with the
  same permissions role as the user who triggered the workflow run. This causes
  case, you will also need to pass the new token to ``actions/checkout`` (as
  the ``token`` input) in order to gain push access.

 .. note::
  As of $NEW_RELEASE_TAG, Python Semantic Release automatically detects and converts
  shallow clones to full clones when needed. While you can still use ``fetch-depth: 0``
  with ``actions/checkout@v4`` to fetch the full history upfront, it is no longer
  required. If you use the default shallow clone, Python Semantic Release will
  automatically fetch the full history before evaluating commits. If you are using
  an older version of PSR, you will need to unshallow the repository prior to use.

 .. note::
  As of $NEW_RELEASE_TAG, the verify upstream step is no longer required as it has been
  integrated into PSR directly. If you are using an older version of PSR, you will need
diff --git a/docs/configuration/configuration-guides/uv_integration.rst b/docs/configuration/configuration-guides/uv_integration.rst
          uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
          with:
            ref: ${{ github.sha }}
            fetch-depth: 0

        - name: Setup | Force correct release branch on workflow sha
          run: git checkout -B ${{ github.ref_name }}
          uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
          with:
            ref: ${{ github.ref_name }}
            fetch-depth: 0

        - name: Setup | Force release branch to be at workflow sha
          run: git reset --hard ${{ github.sha }}
diff --git a/src/semantic_release/cli/commands/version.py b/src/semantic_release/cli/commands/version.py
        logger.info("Forcing use of %s as the prerelease token", prerelease_token)
        translator.prerelease_token = prerelease_token

    # Check if the repository is shallow and unshallow it if necessary
    # This ensures we have the full history for commit analysis
    project = GitProject(
        directory=runtime.repo_dir,
        commit_author=runtime.commit_author,
        credential_masker=runtime.masker,
    )
    if project.is_shallow_clone():
        logger.info("Repository is a shallow clone, converting to full clone...")
        project.git_unshallow(noop=opts.noop)

    # Only push if we're committing changes
    if push_changes and not commit_changes and not create_tag:
        logger.info("changes will not be pushed because --no-commit disables pushing")
        license_name="" if not isinstance(license_cfg, str) else license_cfg,
    )

    project = GitProject(
        directory=runtime.repo_dir,
        commit_author=runtime.commit_author,
        credential_masker=runtime.masker,
    )

    # Preparing for committing changes; we always stage files even if we're not committing them in order to support a two-stage commit
    project.git_add(paths=all_paths_to_add, noop=opts.noop)
    if commit_changes:
diff --git a/src/semantic_release/gitproject.py b/src/semantic_release/gitproject.py
        with Repo(str(self.project_root)) as repo:
            return repo.is_dirty()

    def is_shallow_clone(self) -> bool:
        """
        Check if the repository is a shallow clone.

        :return: True if the repository is a shallow clone, False otherwise
        """
        with Repo(str(self.project_root)) as repo:
            shallow_file = Path(repo.git_dir, "shallow")
            return shallow_file.exists()

    def git_unshallow(self, noop: bool = False) -> None:
        """
        Convert a shallow clone to a full clone by fetching the full history.

        :param noop: Whether or not to actually run the unshallow command
        """
        if noop:
            noop_report("would have run:\n" "    git fetch --unshallow")
            return

        with Repo(str(self.project_root)) as repo:
            try:
                self.logger.info("Converting shallow clone to full clone...")
                repo.git.fetch("--unshallow")
                self.logger.info("Repository unshallowed successfully")
            except GitCommandError as err:
                # If the repository is already a full clone, git fetch --unshallow will fail
                # with "fatal: --unshallow on a complete repository does not make sense"
                # We can safely ignore this error by checking the stderr message
                stderr = str(err.stderr) if err.stderr else ""
                if "does not make sense" in stderr or "complete repository" in stderr:
                    self.logger.debug("Repository is already a full clone")
                else:
                    self.logger.exception(str(err))
                    raise

    def git_add(
        self,
        paths: Sequence[Path | str],
Original file line number	Diff line number	Diff line change
Expand Up		@@ -875,17 +875,16 @@ to the GitHub Release Assets as well.
		contents: write

		steps:
		# Note: We checkout the repository at the branch that triggered the workflow
		#with the entire history to ensure to match PSR's release branch detection
		#andhistory evaluation.
		#However, we forcefully reset thebranch to the workflow sha because it is
		#possible thatthebranch wasupdated while the workflow was running. This
		#prevents accidentally releasing un-evaluatedchanges.
		# Note: We checkout the repository at the branch that triggered the workflow.
		#Python Semantic Release will automatically convert shallow clones to full clones
		#if needed to ensure properhistory evaluation. However, we forcefully reset the
		# branch to the workflow sha because it is possible that the branch was updated
		#whiletheworkflow wasrunning, which prevents accidentally releasing un-evaluated
		# changes.
		- name: Setup \| Checkout Repository on Release Branch
		uses: actions/checkout@v4
		with:
		ref: ${{ github.ref_name }}
		fetch-depth: 0

		- name: Setup \| Force release branch to be at workflow sha
		run: \|
Expand DownExpand Up		@@ -959,11 +958,6 @@ to the GitHub Release Assets as well.
		one release job in the case if there are multiple pushes to ``main`` in a short period
		of time.

		.. warning::
		You must set ``fetch-depth`` to 0 when using ``actions/checkout@v4``, since
		Python Semantic Release needs access to the full history to build a changelog
		and at least the latest tags to determine the next version.

		.. warning::
		The ``GITHUB_TOKEN`` secret is automatically configured by GitHub, with the
		same permissions role as the user who triggered the workflow run. This causes
Expand All		@@ -974,6 +968,14 @@ to the GitHub Release Assets as well.
		case, you will also need to pass the new token to ``actions/checkout`` (as
		the ``token`` input) in order to gain push access.

		.. note::
		As of $NEW_RELEASE_TAG, Python Semantic Release automatically detects and converts
codejedi365 marked this conversation as resolved. Show resolvedHide resolved
		shallow clones to full clones when needed. While you can still use ``fetch-depth: 0``
		with ``actions/checkout@v4`` to fetch the full history upfront, it is no longer
		required. If you use the default shallow clone, Python Semantic Release will
		automatically fetch the full history before evaluating commits. If you are using
		an older version of PSR, you will need to unshallow the repository prior to use.

		.. note::
		As of $NEW_RELEASE_TAG, the verify upstream step is no longer required as it has been
		integrated into PSR directly. If you are using an older version of PSR, you will need
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -161,7 +161,6 @@ look like this:
		uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
		with:
		ref: ${{ github.sha }}
		fetch-depth: 0

		- name: Setup \| Force correct release branch on workflow sha
		run: git checkout -B ${{ github.ref_name }}
Expand DownExpand Up		@@ -259,7 +258,6 @@ look like this:
		uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
		with:
		ref: ${{ github.ref_name }}
		fetch-depth: 0

		- name: Setup \| Force release branch to be at workflow sha
		run: git reset --hard ${{ github.sha }}
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -496,6 +496,17 @@ def version( # noqa: C901
		logger.info("Forcing use of %s as the prerelease token", prerelease_token)
		translator.prerelease_token = prerelease_token

		# Check if the repository is shallow and unshallow it if necessary
		# This ensures we have the full history for commit analysis
		project = GitProject(
		directory=runtime.repo_dir,
		commit_author=runtime.commit_author,
		credential_masker=runtime.masker,
		)
		if project.is_shallow_clone():
		logger.info("Repository is a shallow clone, converting to full clone...")
		project.git_unshallow(noop=opts.noop)

		# Only push if we're committing changes
		if push_changes and not commit_changes and not create_tag:
		logger.info("changes will not be pushed because --no-commit disables pushing")
Expand DownExpand Up		@@ -688,12 +699,6 @@ def version( # noqa: C901
		license_name="" if not isinstance(license_cfg, str) else license_cfg,
		)

		project = GitProject(
		directory=runtime.repo_dir,
		commit_author=runtime.commit_author,
		credential_masker=runtime.masker,
		)

		# Preparing for committing changes; we always stage files even if we're not committing them in order to support a two-stage commit
		project.git_add(paths=all_paths_to_add, noop=opts.noop)
		if commit_changes:
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -90,6 +90,42 @@ def is_dirty(self) -> bool:
		with Repo(str(self.project_root)) as repo:
		return repo.is_dirty()

		def is_shallow_clone(self) -> bool:
		"""
		Check if the repository is a shallow clone.

		:return: True if the repository is a shallow clone, False otherwise
		"""
		with Repo(str(self.project_root)) as repo:
		shallow_file = Path(repo.git_dir, "shallow")
		return shallow_file.exists()

		def git_unshallow(self, noop: bool = False) -> None:
		"""
		Convert a shallow clone to a full clone by fetching the full history.

		:param noop: Whether or not to actually run the unshallow command
		"""
		if noop:
		noop_report("would have run:\n" " git fetch --unshallow")
		return

		with Repo(str(self.project_root)) as repo:
		try:
		self.logger.info("Converting shallow clone to full clone...")
		repo.git.fetch("--unshallow")
		self.logger.info("Repository unshallowed successfully")
		except GitCommandError as err:
		# If the repository is already a full clone, git fetch --unshallow will fail
		# with "fatal: --unshallow on a complete repository does not make sense"
		# We can safely ignore this error by checking the stderr message
		stderr = str(err.stderr) if err.stderr else ""
		if "does not make sense" in stderr or "complete repository" in stderr:
		self.logger.debug("Repository is already a full clone")
		else:
		self.logger.exception(str(err))
		raise

		def git_add(
		self,
		paths: Sequence[Path \| str],
Expand Down