How to get started with Insiders? For the Renovate docs site.

[HonkingGoose]

The Renovate team started sponsoring Material for MkDocs. 🥳 For now we're only using the public stuff. I'd like to use the cool new features from Insiders. But I don't understand how the Renovate maintainers should set up Insiders. I'm getting difficult questions that I don't know to answer.

I'll start by explaining:

• our current setup
• the wanted division of reponsiblities
• what I think are the next steps

Pinging @rarkins and @viceice so they can help answer any incoming questions from the Material for MkDocs maintainer. 😉

Current set up for the Renovate docs repository

As best as I understand, this is our current set up:

mindmap
  root((docs repo))
    Git submodule dependency on renovatebot/renovate
      updates automatically via Renovate bot
    build
      custom scripts
       pulls in Git submodule content
       autogenerate parts of docs
         fetch open issues
         other stuff
      tests
        Cypress smoketest
        mkdocs build strict mode
    publishing
      to GitHub Pages via gh pages branch
      automatic after merge to main branch
    development
      locally
      with Codespaces
      with Gitpod
    collaboration
      pulls from HonkingGoose's fork
      HonkingGoose edits config

Loading

Division of responsibilities

Here's how I would like to divide the reponsibilities:

mindmap
  root((insiders fork))
    HonkingGoose
      read access only
        fork of fork?
        previews build with Codespaces
        edits config via PR       
    maintainers
      direct access
      keep tokens safe
      keep build working
      keep Insiders fork private
      keep publishing working

Loading

Is something like this even possible? Can I have a private fork of Renovate's fork of Insiders? 🙃

Have you read the docs?

Yes, I read the Insiders docs. The problem is that our configuration and publishing is very complex already. So I don't feel comfortable to help the Renovate maintainers.

What's the first step?

I've listed what I think are the first things to figure out, or decide on. I'll gladly hear your advice on how to:

• Keep the Insiders stuff private, while allowing HonkingGoose to collaborate.
• Set up a (bot) account or token for Insiders? Which is best?
• Keep any tokens secure?
• Preview Insiders-only stuff before it lands in production.
• Redirect publishing from public stuff to Insiders.

[kamilkrzyskow]

Hello @HonkingGoose,
I will say that such complex pipelines and fully automated CI approach with bots isn't my area of expertise, but I think I should at least be able to start the discussion 😃

By "maintainers" I understand you mean people that are members of the renovatebot organization that maintain the repositories.
But perhaps you also include the outside "contributors" that make PR's to the public repository, so it would be good to make sure we're understanding it the same way.

At the start I understood that you're a part of the Renovate team, therefore I'm assuming you do have access to their private renovatebot/mkdocs-material-insiders? If GitHub UI doesn't allow you to create a personal fork of the insiders fork repository, then the only option is to create a private hard fork (so a separate repository not marked as fork by GitHub). On your local machine you can create multiple git remote to point to your personal origin and the renovate fork repositories.

I'm getting difficult questions that I don't know to answer.

I'm not sure what are the other questions, but I will comment on the first steps.

Keep the Insiders stuff private, while allowing HonkingGoose to collaborate.

So this makes me think that you don't have access to the private fork repository and you're asking:

• How to allow non-Insiders contributors to build the documentation while using Insiders-only features?

To keep Insiders safe and secure, no non-Insider contributor can gain access to a token or touch the files directly.
You can look at how https://github.com/privacyguides/privacyguides.org does it. They offer preview deployments via a Netlify bot for pull requests and merge them later into main.

Set up a (bot) account or token for Insiders? Which is best?

Which is best for what exactly? But mostly doesn't matter, bot with access permission to a private repository is the same as a bot with a token to access the repository.

Keep any tokens secure?

As long as you don't put the token in a file and commit it anywhere it should be secure. You can set environmental variables for private repositories and the whole organization.

Preview Insiders-only stuff before it lands in production.
Redirect publishing from public stuff to Insiders.

I'm not sure if I understood the second thing, but the same as written above. You'd need to setup a workflow that is triggered with pull requests and builds and deploys the files to a temporary host OR instead of a workflow have a bot like Privacy Guides do so with Netlify.

I hope that any of this could allow you to progress further with the upgrade ✌️

[HonkingGoose]

Thank you @kamilkrzyskow for the really quick response!

I will say that such complex pipelines and fully automated CI approach with bots isn't my area of expertise, but I think I should at least be able to start the discussion 😃

I don't fully understand it either, so that's okay. 😄

By "maintainers" I understand you mean people that are members of the renovatebot organization that maintain the repositories.
But perhaps you also include the outside "contributors" that make PR's to the public repository, so it would be good to make sure we're understanding it the same way.

Good point! Maintainers means members of the renovatebot organization, which have final say over the repositories. I'm a contributor, and usually work from my fork of their repositories, making PRs to their public repositories.

At the start I understood that you're a part of the Renovate team, therefore I'm assuming you do have access to their private renovatebot/mkdocs-material-insiders?

I'm sorta-kinda part of the team, in that I'm doing this in my free time, don't get paid for it, and don't want write access. So this is me basically doing hobby work on the docs, and making the docs site look nicer by configuring the new Material for MkDocs features. 😄

I don't know if the Renovate maintainers have already forked the Insiders repository. I think they're still at the stage of figuring out the best way to fork:

• Fork Insiders from the renovatebot account
• Fork Insiders from a new bot account just for the Insiders access
• Something else that's better?

I don't know if I can be invited as collaborator on a private fork?

If GitHub UI doesn't allow you to create a personal fork of the insiders fork repository, then the only option is to create a private hard fork (so a separate repository not marked as fork by GitHub). On your local machine you can create multiple git remote to point to your personal origin and the renovate fork repositories.

I really like using GitHub's Codespaces, because then I don't need to figure out or update the development environment. I can just open a Codespace, tinker with the Material for MkDocs configuration, build the site, and see the preview. I create a PR and then throw away the codespace when it's merged.

Could I still use Codespaces when I hold a private hard fork?

I'm not sure what are the other questions, but I will comment on the first steps.

It's mostly them asking how to deal with accessing Insiders safely. I'm mostly worried how I can see and propose changes to the Insiders-only config. I'd also like to have a easy way to preview the changes, so something like Vercel/Netlify or Codespaces.

Set up a (bot) account or token for Insiders? Which is best?

Which is best for what exactly? But mostly doesn't matter, bot with access permission to a private repository is the same as a bot with a token to access the repository.

The goal here is to prevent leaking the Insiders-only stuff, prevent leaking tokens, and prevent me from doing stupid stuff by accident. I can probably get invited on the private fork of Insiders, but I don't know if that is enough for me to create PRs then. To me it seems that you need write level access on that private fork to do useful things, like create branches, and commit changes. But when I have write access that's another risky thing to deal with. I'd like the maintainers-proper to be responsible for that stuff. 😄

I think the maintainers also want to spread the Insiders access over multiple members, so that they're not locked out when something happens to a member.

Again, thank you for your response. I'll let the Renovate maintainers respond to your and my post in detail.