What's the URL of your project? What's the URL of the build where you're noticing this?

What's the URL of your project? What's the URL of the build where you're noticing this?

Added. I pasted the URLs into the template wrong I guess

READTHEDOCS_GIT_IDENTIFIER is the raw commit SHA

Where I should check the content of this variable in your documentation? I'm not able to find the the SHA in the page you linked.

the example line of - uses: KSPModdingLibs/KSPBuildTools/.github/actions/assemble-release@f89bab355278f61eabb8d8848746a9ce74a256bd is auto-generated using that environment variable

It should say - uses: KSPModdingLibs/KSPBuildTools/.github/actions/[email protected] since the tag name being built is 0.0.2-alpha.7

I'm not able to reproduce this issue. I did a try at https://test-builds.readthedocs.io/en/full-feature/environment-variables.html and you can see there that READTHEDOCS_GIT_COMMIT_HASH: 185f27fa0b5d052862be2fca53c19ddb22d325e6 and READTHEDOCS_GIT_IDENTIFIER: full-feature. Those variables are pointing to the correct values.

I think that variable is never the tag name. It seems that it can only be a branch name and or a commit sha when it's a tag. Using my previous branch, I created a tag named v0.1-full-feature and built it on Read the Docs.

Taking a look at the same page, https://test-builds.readthedocs.io/en/v0.1-full-feature/environment-variables.html, we can see that both environment variables have the same value and it's a commit sha.

We use Version.identifier for READTHEDOCS_GIT_IDENTIFIER and based on what this comment says, it will always be a SHA if it's a tag:

I found that calling git describe as you mentioned you can get the tag's name from a commit:

▶ git describe --tags 185f27fa0b5d052862be2fca53c19ddb22d325e6
v0.1-full-feature

This is a bug and we should fix it.

I'm adding this issue to the roadmap. We have another user hitting this bug.

So, looks like we aren't saving the branch/tag name that was used in a build, we merely rely on the commit. We can infer the branch/tag name from the version, but that doesn't work for the stable version (we don't save the tag name for stable #10935), and for build from PRs (builds only know the PR number, not the branch). Are we okay with a solution that doesn't work for those two cases?

I understand if we don't have the branch/tag name we will have the commit, right? We can use git describe as I mentioned in my previous comment to get the branch/tag name in those cases.

That will work for the case of stable I guess, but it won't work for PR builds, as we fetch it as external-{pr number}. Actually, not sure what should be the correct value for PR builds, if they are from the same repo it makes sense that the git id is the name of the branch, but for PR from forks, it doesn't make sense to use that.

For PR we will have a commit hash as well. That's what we need to return here and it will be consistent.

For PR we will have a commit hash as well. That's what we need to return here and it will be consistent.

Do you mean return the commit itself? That doesn't seem consistent, as we will return the branch/tag name on all other cases.

Meh, I'm sorry, I got confused.

if they are from the same repo it makes sense that the git id is the name of the branch

👍🏼

but for PR from forks, it doesn't make sense to use that.

We can return what GitHub shows for this cases: <username>:<branch> (example: PyCampES/pycampes#90). If that's too hard to get, we can return unknown for now and leave that case for later.

Hi! Just came here to say that I also have this issue.

I published my documentation using tags as a way to provide permalinks, and I use sphinx.ext.linkcode to point to the corresponding code on GitHub.

However, when publishing from tags, READTHEDOCS_GIT_IDENTIFIER points to the commit SHA, not the tag name itself. While it is essentially the same, it would be better if the tag name could be provided by READTHEDOCS_GIT_IDENTIFIER, so the URL looks just better (IMO).

E.g., the following page shows documentation for tag icmlcn2025
https://differt.eertmans.be/icmlcn2025/reference/_autosummary/differt.geometry.TriangleMesh.html#differt.geometry.TriangleMesh
but clicking on the source link opens up https://github.com/jeertmans/DiffeRT/blob/5b9879a2d07625b976a84f2f7aa829259cb0d4b1/differt/src/differt/geometry/_triangle_mesh.py#L84-L698.

For your information, I build the link to source code with:

git_ref = os.environ.get("READTHEDOCS_GIT_IDENTIFIER", "main")

def linkcode_resolve(domain: str, info: dict[str, Any]) -> str | None:

    # ...

    return f"https://github.com/jeertmans/DiffeRT/blob/{git_ref}/{filename}{lines}"

Note that the issue also occurs on pull-request builds (but I can this is related to what you said above).

Not sure if that can help you :-)