How to get Insiders release tags without access to Insiders?

[normandy7]

Description

At some point a plugin broke on our end with the latest Insiders release and we'd need to pin mkdocs-material-insiders to a specific version. However, on the How to upgrade docs page, the linked tags list returns 404 and by guessing how to fill out the numbers in the installation command's URL, I couldn't successfully find a release that worked.

Related links

• https://squidfunk.github.io/mkdocs-material/insiders/upgrade/
• https://github.com/squidfunk/mkdocs-material-insiders/tags

Proposed change

No response

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[alexvoss]

The link to the tags list works fine for me. Could this have been a temporary glitch on Github's side?

[squidfunk]

Note that you need Insiders access on your account to get to that site, so maybe the user that clicked the list does not have access to it. This might have been the issue, but I'm not really sure if we want to add an extensive list of all versions to our docs.

[normandy7]

Ah, that would explain it. It wasn't very apparent from the page itself that the link goes to restricted content. Thanks

[kamilkrzyskow]

The docs could include a footnote for that tags list link leading to Insiders:

To see the list of tags instead of a 404 page you need to login to a GitHub account with Insiders access.
If your team uses a fork of the project you can check the available tags with git show-ref --tags on the machine with access to the forked repository.

[alexvoss]

This may a bit obvious as well as out of our control but why the heck does GitHub send a 404 message? That is misleading. There, got it off my chest, feeling better already...

[kamilkrzyskow]

https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource
Because of bad actors online trying find out if private repositories exist. I agree it's a bit weird, as knowledge that something exists won't really help in getting unauthorized access to it. So let's call the reason privacy, but in that case it should be configurable 😅

[squidfunk]

I'm converting this to a discussion. If we can deduce something concrete that should be added to the docs, we can do it, but I'm not sure what should be done.

[squidfunk]

The simplest option when you do not have access to Insiders is to check our changelog, as it lists all versions chronologically. You can also get the fully qualified Insiders versions from it. The only thing you need to do is to replace + with -. We cannot use + (which starts a local Python version qualifier), as Docker doesn't allow for + characters, so we need to use - everywhere.

Example

Take the latest Insiders version from the changelog to date:

mkdocs-material-9.5.4+insiders-4.50.0

Drop the mkdocs-material- prefix and replace the +:

9.5.4-insiders-4.50.0

You can now use this as a tag to install a specific version of Insiders:

pip install git+https://${GH_TOKEN}@github.com/squidfunk/[email protected]

[normandy7]

Thank you, that is helpful. I did not realize I could access the Insiders tags this way.